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Preface 


This book is a reference manual for the UCSD p-System™* on 
the Texas Instruments Professional Computer. It describes the 
p-System facilities which enable you to develop programs. It is 
designed for a processing professional who is familiar with the 
p-System. The UCSD Pascal™* programming language is not 
described in this manual. 

The following books and manuals may also be of interest to 
you. They are available from SofTech Microsystems. 

UCSD Pascal Reference Manual 
UCSD p-System 8086 Assembler Reference Manual 
UCSD p-System Internal Architecture Reference Manual 
UCSD p-System Optional Products Reference Manual 
UCSD p-System FORTRAN-77 Reference Manual 
UCSD p-System BASIC Reference Manual 
UCSD p-System Assemblers Reference Manual 
UCSD p-System 8086/88/87 Assembler Reference Manual 
UCSD p-System Adaptable System Installation Manual 

DISCLAIMER 

This document and the software it describes are subject to 
change without notice. No warranty expressed or implied covers 
their use. Neither the manufacturer nor the seller is responsible 
nor liable for any consequences of their use. 


* UCSD p-System and UCSD Pascal are trademarks of the Regents of the 
University of California. 
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Introduction 


HOW TO USE THIS MANUAL 

This book is a reference manual for use with the UCSD p-System 
on the Texas Instruments Professional Computer. It describes 
the p-System facilities which enable you to develop programs. 

Chapter 2, Compiling Programs and Units, covers the Pascal 
compiler. The UCSD Pascal programming language is not cov¬ 
ered in this manual. You should see the UCSD Pascal reference 
manual, TI Part Number 2232401-0001, if you are interested in a 
thorough description of the language. This chapter also describes 
units, segments, and libraries. These facilities are used when you 
separately compile program modules. Using them, you can com¬ 
pile and run much larger programs than you would otherwise be 
able to within a given computer's memory and disk space 
limitations. 

Chapter 3, User Interface, describes several p-System facilities 
that can assist your programs in presenting a clean and portable 
user interface. For example, the p-System can be completely hid¬ 
den underneath your application’s own environment. Programs 
can be chained together and called from a simple menu driver 
that appears when a disk is bootstrapped. Whether or not you 
use this approach, you may wish to take advantage of screen 
handling and error interception facilities described in this 
chapter. 

Chapter 4, File Management Units, covers the file management 
units. These allow your programs to manipulate disk files in a 
similar fashion to the filer. For example, files can be listed and 
removed, volumes can be crunched, and so forth. 
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Chapter 5, Debugging and Analysis, covers the debugger and the 
performance monitor units. The debugger is a very powerful tool 
for finding and correcting errors that might exist in programs 
you write. The performance monitor allows you to accumulate 
statistical information concerning various performance-related 
issues. Many of the utilities described in Chapter 6 are also valu¬ 
able as program debugging and analysis aids. 

Chapter 6, Utilities Programs, describes several utility programs 
that are generally useful. Most of them are specifically used 
during program development. 


BACKGROUND 

In June 1979, SofTech Microsystems in San Diego, began to 
license, support, maintain, and develop the p-System. The result¬ 
ing effort to build the world’s best small computer environment 
for executing and developing applications has dramatically in¬ 
creased the growth and use of the p-System. The first p-System 
ran on a 16-bit microprocessor. Today, the p-System runs on 
8-bit, 16-bit, and 32-bit machinespincluding the Z80 TMi , 8080/ 
8085, 8086, 6502, 6809, 68000, 9900, PDP-11 TT2 , LSI-11™ 2 , and 
VAX™ 2 . 


The p-System began as the solution to a problem. The University 
of California at San Diego needed interactive access to a high- 
level language for a computer science course. In late 1974, Ken¬ 
neth L. Bowles began directing the development of the solution 
to that problem: the p-System. He played a principal role in the 
early development of the software. 

In the summer of 1977, a few off-campus users began running a 
version of the p-System on a PDP-11. When a version for the 
8080 and the Z80 began operating in early 1978, outside interest 
increased until a description of the p-System in Byte Magazine 
drew over one thousand inquiries. 


1 Trademark of Zilog Incorporated. 

2 Trademark of Digital Equipment Incorporated. 
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As interest grew, the demand for the p-System could not be met 
within the available resources of the project. SofTech Microsys¬ 
tems was chosen to support and develop the p-System because of 
its reputation for quality, high technology, and language design 
and implementations. 

Now the p-System is available on the Texas Instruments Profes¬ 
sional Computer. 


DESIGN PHILOSOPHY 

The development team, many of whom continued their efforts on 
behalf of the system at SofTech Microsystems, decided to use 
stand-alone, personal computers as the hardware foundation for 
the p-System rather than large, time-sharing computers. They 
chose Pascal for the programming language because it could 
serve in two capacities: the language for the course and the sys¬ 
tem software implementation language. 

The development team had three primary design concerns: 

• The user interface must be oriented specifically to the nov¬ 
ice, but must be acceptable to the expert. 

• The implementation must fit into personal, stand-alone 
machines (64K bytes of memory, standard floppy disks, and 
a display unit). 

• The implementation must provide a portable software envi¬ 
ronment where code files (including the operating system) 
can be moved intact to a new microcomputer. In this way, 
application programs written for one microcomputer can 
run on another microcomputer without recompilation. 

The current design philosophy at SofTech Microsystems, where 
the p-System continues to evolve, is basically the same as the 
original philosophy. 
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User-Friendly 

The p-System continuously identifies its current mode 
and the options available to you in that mode. This is 
accomplished by using menus, displays, and prompts. 
You can select an option from a menu by pressing a 
single-character activity. The system’s displays then 
guide your interactions with the computer. As you gain 
more experience, you can ignore the continuous status 
information—unless it is needed. 


Portability 

The p-System is more portable than any other microcom¬ 
puter system. It protects your software investments 
without restricting hardware options. The p-System does 
this by compiling programs into p-code—rather than 
native machine language—thus, allowing these code files 
to be executed on any microcomputer that runs the 
UCSD p-System. 
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INTRODUCTION 


This chapter is principally concerned with the UCSD Pascal 
compiler on the Texas Instruments Professional Computer. The 
UCSD Pascal programming language is not covered here. If you 
are interested in a detailed description of UCSD Pascal, consult 
the UCSD Pascal reference manual. 

Separate compilation is also covered in this chapter. Specifically, 
the UCSD Pascal unit construct, program segmentation, and 
code file libraries are addressed. 


USING THE COMPILER 

The compiler takes a text file as input and generates a machine- 
portable code file as output. The generated code file contains p- 
code, which is executed by the p-System’s p-machine emulator. 
This emulator is written in 8086 assembly language and runs 
directly on the Texas Instruments Professional Computer’s hard¬ 
ware. 

You can start the compiler by selecting the C(ompile or R(un 
activity of the command menu. If a work file exists, it is com¬ 
piled. Otherwise, you are prompted for a text file to compile, like 
this: 


Compi lewhat text 7 _ 


Enter the name of the text file, but do not include the .TEXT suf¬ 
fix (which is assumed). Next, you are asked: 


To what codefi le ? _ 


Here, you should enter the name of the code file that you want the 
compiler to produce. Do not include the .CODE suffix (which, 
once again, is assumed). If you simply press the RETURN key, 
the code file *SYSTEM.WRK.CODE is produced. The next 
prompt is: 


Output fi le for compi led listing ? (<cr> for none) _ 
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This allows you to indicate where you want the compiled listing 
to be sent. You can respond with a file name, with a communica¬ 
tions volume such as PRINTER: or CONSOLE:, or simply by 
pressing the RETURN key. When you enter a file name, the list¬ 
ing is placed in the file. You can use the suffix .TEXT, but it is 
always appended if you do not. If you specify a communications 
volume, the listing is sent there (where it is printed, displayed, or 
transmitted). When you simply press the RETURN key, no list¬ 
ing is produced. If you wish to exit the compiler, rather than 
respond to either the code file name prompt or the listing destina¬ 
tion prompt, press the ESC key followed by the RETURN key. 

The $L Pascal compiler option can also create a compiled listing, 
as described later in this chapter. If you indicate a file or commu¬ 
nications volume in response to this prompt, however, the compi¬ 
ler option is overridden. (You should note that .TEXT is not 
automatically appended with the $L option as it is with this 
prompt.) 

While the compiler is running, it displays a report of its progress 
on the screen in this manner: 


- '\ 


Pascal compi ler- release level VERSION 

< 0 >. 

INITIALIZE 

< 1 9>. 

AROUTINE 

< 61 >. 

< 111 >. 

MY PROG 

< 119 >. 

237 l i nes compi l ed 

INITIALI . 

MYPROG . . 



^ __ / 
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During the first pass, the compiler displays the name of each rou¬ 
tine. In this example, INITIALI, AROUTINE, and MYPROG 
are the routines. The numbers enclosed within angle brackets, 
< > , are the current line numbers and each dot on the screen rep¬ 
resents one source line compiled. 

During the second pass, the names displayed are segments. In 
the example, MYPROG is the program segment and INITIALI 
is a segment routine. Here the dots represent one routine within 
the segment. MYPROG contains both itself and AROUTINE. 

You can suppress this output if you want by using the $Q compi¬ 
ler option, described later. 

If the compilation is successful, that is, if no compilation errors 
are detected, the compiler creates a code file. This file is called 
*SYSTEM.WRK.CODE if you are using work files or if you press 
the RETURN key in response to the compiler's To what code 
file? prompt. Otherwise, it is given the name that you specify 
in response to that prompt. 

When you select R(un (instead of C(ompile), the resulting code file 
is automatically executed. If you have a work code file, or if you 
have just compiled a program, R(un simply executes it. 
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Syntax Errors 


If your program text does not conform to the rules of the 
Pascal programming language, the compiler issues a syn¬ 
tax error. When this happens, the text where the error 
occurred is displayed, along with an error number or mes¬ 
sage. Here are two examples: 



This is the same error displayed twice (the first line of a 
program is incorrect). In the first case, the error message 
is displayed. In the second case, the error number is 
displayed. You only receive the error message if the file 
^SYSTEM. SYNTAX is available. If 
*SYSTEM.SYNTAX is not present, you need to look up 
the error number in the appropriate appendix to this 
manual. 

After each syntax error, a message like one of these is 
displayed and the compiler gives you the option of press¬ 
ing the space bar to continue the compilation, the ESC 
key to terminate it, or E to enter the editor. 
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You can press the space bar for every syntax error in the 
program if you wish. In this way, you can usually dis¬ 
cover all of the errors that exist. (However, some syntax 
errors can confuse the compiler and hide other syntax 
errors.) A code file is never produced if syntax errors are 
found but a compiled listing can be produced. You can use 
such a listing to keep track of the errors so that you can 
correct them all at once. 

If you elect to press E after a syntax error, the compila¬ 
tion is terminated (as it is with the ESC key). However, 
you can now fix the error immediately because the editor 
is automatically called. If the file that you are compiling 
is a work file, it is read into your work space. If it is not a 
work file, you are asked to specify which file you want to 
edit (in the editor’s normal fashion). In either case, when 
the file is read into the work space, the cursor is placed at 
the exact spot where the error was detected. The error 
message or number is redisplayed and you must press the 
space bar to begin editing so that you can fix the problem. 
When a syntax error occurs in an include file (see the $1 
compiler option), you must be sure to specify that file cor¬ 
rectly as you enter the editor. You are informed of the 
name of the include file after the Line it portion of the 
syntax error message. 

If both the $Q and $L compiler options are in effect, the 
compilation continues and the syntax error is only 
reported in the listing file. In this case, the screen remains 
undisturbed by syntax errors. 

Compiled Listings 

The compiler may optionally produce a listing of the 
compiled source. This listing contains your text along 
with information about the compilation. Compiled list¬ 
ings are very useful for reference as well as analysis and 
debugging purposes. 
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In order to produce a compiled listing, you can use the 
compiler's menu for a listing file which is described 
above. Alternatively, you can use the $L compiler option 
which is described in the following section entitled compi¬ 
ler options. 

Here is the entire compiled listing for a very simple 
program: 


Pascal Compiler VERSION 1/1/83 Page 1 

1 0 0:d 1 {$L list, text} 

2 2 l:d 1 Program Comp. Listings Example; 

3 2 1:0 0 Begin 

4 2 1:0 0 { 

5 2 1:0 0 This is an example listing of 

6 2 1:0 0 an empty program. 

7 2 1:0 0 } 

8 2 :0 0 End. 

End of Compilation. 


Here is a sample portion of a more complex listing: 

393 10 12:d 1 Procedure iocheck; 

{ commented out} {; 

{ commented out V } This procedure will check the i o operations of the 
{ commented out V } index as it is in the process of rebuilding 


397 

10 

12:d 

1 

} 

398 

!() 

12:0 

0 Begin 

399 

10 

12:1 

0 

If ioresult < > 0 Then 

400 

10 

12:2 

6 

Begin 

401 

10 

12:3 

6 

pl A := index I/O failure.': 

402 

10 

12:3 

32 

prompt(errorline): 

403 

10 

12:2 

38 

End: { if ioresult < > 0 then } 

404 

10 

12:0 

38 

End; { iocheck } 

405 

10 

12:0 

50 


406 

10 

13:d 

1 Procedure dropindex(position: isamcoverage); 




In those lines that are not marked as commented out 
(which is intended to warn you that a comment may have 
accidentally eliminated some Pascal code), the numbers 
that precede a source line are: 

• The line number. For example, 397 in the listing 
above. 

• The Pascal segment number. This entire example is 
part of segment number 10. 

• The routine number followed by a colon and the lex 
level. In the example, procedure iocheck is routine 
number 12 and procedure dropindex is routine 13. 
The lex level indicates how deeply the text is nested 
within Pascal begin-end pairs. 

• The number of bytes of data or code storage which 
the routine requires at that point. For example, the 
IF statement, line 399, requires 6 bytes of p-code. 
The entire procedure iocheck requires 50 bytes of 
p-code. 

Lines which contain declarations (variables, constants, 
and so forth) show the letter d following the routine num¬ 
ber. In the listing above, lines 393 and 397 are examples 
of this. 

When the module that you are compiling uses a unit, the 
interface section of that unit appears in the compiled list¬ 
ing with the letter u where the d normally appears. Also, 
the additional line USING < UNITNAME> appears in 
the heading to make it easier for you to distinguish inter¬ 
face sections from the text that you are specifically com¬ 
piling. 
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Here is a portion of a compiled listing that shows syntax 
errors: 


596 10 1:5 228 

—> Error #104 


597 10 1 

5 239 

598 10 1 

5 239 

599 10 1 

5 239 

600 10 1 

5 242 

601 10 1 

5 242 

602 10 1 

6 242 


~> Error #104 
previous error — line 596 
607 10 1:6 271 


lastpageitem := min(lastentry,lastentry); 


{ loop through the page } 

Pagelnx := 0; 

{ function returns next greater } 

Repeat {until found or (Pagelnx > lastentry)} 
AssertlPage Inx< lastpage item,'bad Page Inx ): 


found := (data([Page!nx].key > key): 


This shows two instances of error 104. This particular 
error indicates that an undeclared identifier was 
found —lastpageitem is the problem in both cases. An 
actual message indicating undeclared identifier would 
have been listed if the file *SYSTEM.SYNTAX had been 
available. 


Error messages indicate the position of the previous syn¬ 
tax error. In this example, line 596 contains the first syn¬ 
tax error and line 602, which contains the second, 
references line 596 as the previous syntax error. 
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Compiler Options 


You may direct some of the compiler’s actions by the use 
of compiler options embedded in the source code. Compi¬ 
ler options are a set of commands that may appear within 
pseudo-comments. A pseudo-comment is like any other 
Pascal comment (it is surrounded by (* and *), or by { and 
}). However, a dollar sign immediately follows the left- 
hand delimiter, for example: 

{$1+} 

(*$U MOLD.CODE*) 

{SI + ,S—,L+} 

(*$R A *) 


There are two kinds of compiler options: switch options 
and string options. A switch option is a letter followed by 
a +, —, or A . A string option is a letter followed by a 
string. (In the examples above, the second is a string 
option; the others are switch options.) A pseudo-comment 
can contain any number of switch options (separated by 
commas), and zero or one string options. If a string option 
is present in a pseudo-comment, it must be the last 
option. The string is delimited by the option letter and 
the end of the comment. 

If the pseudo-comment uses (* and *), the string in a 
string option cannot contain an asterisk (*). 

Some options can appear anywhere within the source 
text. Others must appear at the beginning of the file (be¬ 
fore the reserved word PROGRAM or UNIT). 

Switch options are either toggles or stack options. If a 
switch option is a toggle, a plus ( + ) turns it on, and a 
minus (—) turns it off. The options I and R are stack 
options, as are the conditional compilation flags. 
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With each stack option, the current state (either -f or -) 
is saved on the top of a stack (up to 15 states deep). The 
stack may be popped by a caret A (thus reenabling the 
previous state of that option). If the stack is pushed 
deeper than 15 states, the bottom state of the stack is 
lost. If the stack is popped when it is empty, the value is 
alway s negative (—). 

{$1—} ... current value is ' - no I/O checking 

{$1+} ... current value is '+' 

{$I A } current value is again 

{SI A } ... current value is because this was the default 
{$I A } ... current value isbecause stack is now empty 

The individual compiler options are described below in 
alphabetical order. If you do not use any compiler 
options, their default values will be in effect. Here are the 
default values for the compiler options: 

{$R+,I + ,L—,U+,P+} 

These remain in effect unless you override them. 

The $Q option defaults to Q— if HAS SLOW 
TERMINAL is false and Q+ if HAS SLOW 
TERMINAL is true. (HAS SLOW TERMINAL is a 
data item in SYSTEM.MISCINFO which indicates 
whether or not you have a hard-copy terminal or a dis¬ 
play unit). 

Conditional compilation is also controlled by compile¬ 
time options as described below. 

$B — Begin Conditional Compilation 

B is a string option. It starts compilations of a 
section of conditionally compiled source code. See 
the section on conditional compilation, below. 




$C — Copyright Field 

C is a string option. It places the string directly 
into the copyright field of the code file’s segment 
dictionary. The purpose of this is to have a copy¬ 
right notice embedded in the code file. 

$D — Conditional Compilation Flag 

D is a string option. It is used to declare or alter 
the value of a conditional compilation flag. See 
the following section on conditional compilation. 

$D — Symbolic Debugger 

D is a toggle option. $D+ turns on the symbolic 
debugging information. $D —, which is the 
default, turns this off. For more information see 
Chapter 5 on the Debugger. 

$E — End Conditional Compilation 

E is a string option. It ends a section of condition¬ 
ally compiled source code. 

$1 — I/O Check Option 

There are two options named by I. The first is a 
stack switch option (IOCHECK). 

I + , which is the default, instructs the compiler to 
generate code after each I/O statement in a pro¬ 
gram. This code verifies, at run time, that the I/O 
operation was successful. If the operation was not 
successful, the program terminates with a run¬ 
time error. 

I— instructs the compiler not to generate any I/O 
checking code. In the case of an unsuccessful I/O 
operation, the program continues. 
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When you use the I— option, your programs 
should specifically test IORESULT (an intrinsic 
p-System function) when there is the chance of an 
I/O failure. If I— is used and you do not test 
IORESULT, the effects of an I/O error are unpre¬ 
dictable. 

During program development you should proba¬ 
bly use I-K When your program is thoroughly 
debugged, you may wish to use I— since less 
memory space is required without the I/O check¬ 
ing code. Also, you may wish to intercept I/O 
errors in your program. (For example, the end 
user may enter something incorrect from the 
keyboard. Rather than terminating with an I/O 
error, your program may prompt the user to cor¬ 
rect the problem and try again.) 

81—Include File 

This is a string option. The string (delimited by 
the letter I and the end of the comment) is inter¬ 
preted as the name of a file. If that file can be 
found, it is included in the source file and com¬ 
piled. 

{$1 PROG 2} 

This includes the file PROG2.TEXT in the pro¬ 
gram’s source. 

If the initial attempt to open the include file fails, 
the compiler concatenates. TEXT to the file name 
and tries again. If this second attempt fails, or an 
I/O error occurs while reading the include file, the 
compiler responds with a fatal syntax error. 
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In order that included source can carry its own 
declarations, an include file may contain CONST, 
TYPE, and VAR declarations, optionally fol¬ 
lowed by routine declarations. If this is the case, 
then the {$1...} comment must precede any rou¬ 
tine declarations in the main program. Otherwise, 
the include file must follow normal Pascal order¬ 
ing. 

Include files can be nested to a maximum of three 
files deep. 

Note that if a file name begins with a plus ( + ) or a 
minus ( —), a blank must be inserted between the 
letter I and the string. For example: 

(*$I + PROG 2*) 

$L — Compiled Listing 

You may use $L either as a toggle switch option 
or a string option. When used as a toggle, it turns 
the listing on or off at that point in the source 
text. When used as a string option, it indicates 
the name of the listing file. 

Here are two examples of $L with a string option: 

(*$L LIST.TEXT*) 

(*$L PRINTER:*) 

The first example indicates that the compiled list¬ 
ing is to be saved on disk as the file LIST.TEXT. 
The second example sends the listing to the 
printer. 
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When used as a toggle, $L+ turns the listing on 
and $L— turns it off. Using these options, you 
can list only parts of a compilation if you wish. 
The default for the toggle is $L— if you have not 
named a listing file using the compiler’s prompt 
or using $L with a string option. The default is 
$L+ if you have named a listing file in either of 
these ways. No matter which way you name the 
listing file, you can switch the listing on or off 
using $L+ or$L—. 

If you do not specifically name a listing file and 
$L+ is in effect, the compiler writes to 
♦SYSTEM.LST.TEXT. 

You should note that listing files that are sent to 
disk files can be edited as any other text file, 
provided they are created with a .TEXT suffix. 
Without the .TEXT suffix, the p-System treats 
the listing as a data file. With the $L option, 
.TEXT is never appended. However, from the 
compiler’s prompt for a listing file, .TEXT is 
always appended (unless you enter it specifically). 

$N — Native Code Generation 

This is a toggle switch option. The $N+ tells the 
compiler to output information to start native 
code generation. The $N—, which is the default, 
tells the compiler to end code generation. 

$P — Page and Pagination 

The compiler can place page breaks in the com¬ 
piled listing. It does this so that listings sent to 
the printer (or listings sent to files and later 
Transferred to the printer) break across page 
boundaries. A form-feed character ASCII FF 
(American National Standard Code for Informa¬ 
tion Interchange Form Feed) is output every 66 
lines if $P+ is in effect (this is the default). If you 
do not want this, you should use $P—. 
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You can specifically cause a page break at any 
point in a compiled listing by using the $P option 
without a plus or minus sign. 

$Q — Quiet 

This is used to suppress the compiler's standard 
output to the console. $Q+ causes the compiler to 
suppress this output and $Q— causes it to 
resume outputting status information. 

$R — Range Checking 

$R is a stack switch option. The default, $R+, 
causes the compiler to output code after every 
indexed access (for example, to Pascal arrays) to 
check that it is within the correct range. This is 
called range checking. $R— turns range checking 
off. 

Programs compiled with the $R— are slightly 
smaller and faster since they require less code. 
However, if an invalid index occurs or a invalid 
assignment is made, the program is not termi¬ 
nated with a run-time error. Until a program has 
been completely tested, it is suggested that you 
compile with the R+ option left on. 

$R — Real Size Directive 

If $R2 is used the compiler produces a code file 
with 2-word real size. If $R4 is used the com¬ 
piler produces a code file with 4-word real size. 
The Texas Instruments Professional Computer 
will default to 4-word real size. If you try to use 
2-word real size you will receive error message 
17 (Real size mismatch) during execution of the 
program. 
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$T - Title 


$T is a string option. The string becomes the new 
title of pages in the listing file. 

$U — Use Library 

There are two options indicated by $U. One is a 
string option (Use Library). The other, described 
below, is a toggle switch option (User Program). 

With the Use Library option, the string is inter¬ 
preted as a file name. This file should contain 
the unit(s) that your program is about to use. If 
the file is found, the compiler attempts to locate 
the unit(s) that it needs for the subsequent USES 
declarations. If a particular unit is not found 
there, the compiler looks in 
♦SYSTEM.LIBRARY. 

If a client (program or unit) contains USES decla¬ 
rations but no $U option, the compiler looks for 
the used units first in the source file, and then in 
♦SYSTEM.LIBRARY. 

Following is an example of a valid USES clause 
using the $U option: 

USESUNIT1.UNIT2, { Found in ‘SYSTEM.LIBRARY } 

{$U A.CODE} 

UNIT3, { Found in A.CODE } 

{$U B.LIBRARY} 

UNIT4.UNIT5; { Found in B.LIBRARY } 


2-18 







$U — User Program 

This option is used to specify whether the compi¬ 
lation is a user compilation or a p-System 
compilation. If present, it must appear before the 
heading (that is, before the reserved word 
PROGRAM or UNIT). 

When the default $U+ is in effect, a user pro¬ 
gram is indicated. The $U— option allows system 
programmers to compile units with names that 
are predeclared in the p-System. These units are 
actually part of the p-System, itself. $U— also 
sets $R— and $1 — . 

In general you should never use this option, 
unless you need to compile GOTOXY. 

Conditional Compilation 

You can conditionally compile portions of the source text. 
At the beginning of a program’s text you can set a com¬ 
pile-time flag that determines whether or not the condi¬ 
tionally compiled text will be compiled. 

In order to designate a section of text as conditionally 
compilable, you must delimit it by the options $R (for 
begin) and $E (for end). Both of these options must name 
the flag which determines whether the code between 
them is compiled. The flag itself is declared by a $D 
option at the beginning of the source. $D options can be 
used at other locations in the source to change the value 
of an existing flag. 
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Here is an example: 

{$D DEBUG} {declares DEBUG and sets it TRUE} 
PROGRAM SIMPLE; 

BEGIN 

{$B DEBUG} {if DEBUG is TP f E, this section is compiled} 
WRITELN('There is a bug.'); 

{SE DEBUG} {this ends the section} 


{$B DEBUG—} {if DEBUG is FALSE, this section is compiled} 
WRITELNYNothing has failed.'); 

{$E DEBUG} 

END {SIMPLE}. 

Each flag in a program must appear in a $D option before 
the source heading. The name of a flag follows the rules 
for Pascal identifiers. If the flag’s name is followed by a 
minus (—), that flag is set false. The flag can be followed 
by a plus ( + ) which sets it true. If no sign is present, a 
flag is true. The flag’s name can also be followed by a 
caret (A) as shown below. 

The state of a flag can be changed by a $D option that 
appears after the source heading, but the flag must have 
first been declared before the heading. 

The $B and $E options delimit a section of code to be 
conditionally compiled. The $B option can follow the 
flag’s name with a minus ( —), which causes the delimited 
code to be compiled if the flag is false. In the absence of a 
dash, the code is compiled if the flag is true. The flag’s 
name can also be followed by a plus ( + ) or caret (A); these 
are ignored. In a $E option, the flag’s name can be fol¬ 
lowed by a plus ( + ), minus (—), or caret ( A ); these sym¬ 
bols are ignored. 
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The state of each flag is saved in a stack, just as the state 
of a stack switch option is saved. Thus, using a $D option 
with a caret (A) yields the previous value of the flag. Each 
flag’s stack can be as many as 15 values deep. If a 16th 
value is pushed, the bottom of the stack is lost. If an 
empty stack is popped with a caret (a), the value 
returned is always false. 

If a section of code is not compiled, any pseudo-comments 
it may contain are ignored as well. 

{$D DEBUG - } {declares DEBUG and sets it FALSE} 

PROGRAM SIMPLE; 

BEGIN 

{$D DEBUG + } {changes DEBUG to TRUE} 

{$B DEBUG} {if DEBUG is TRUE, this section is compiled} 

WRITELN(There is a hug.'); 

{$E DEBUG} {this ends the section} 


{SD DEBUG A } {restores previous value of DEBUG} 

{...in this case. FALSE} 

{$B DEBUG — } {if DEBUG is FALSE, this section is compiled} 
WRITELNYNothing has failed.'); 

{$E DEBUG} 

END {SIMPLE}. 
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Selective Uses 


Selective uses allows your programs to choose the items 
that you wish to use from a unit’s interface section. You 
can often take advantage of this to reduce compile-time 
space requirements. Also, compilation time can be 
reduced. Both of these are especially noticeable when you 
are using units with large interface sections from which 
you only require a few items. This is because the rest of 
the interface section does not need to be compiled. 

Also, selective uses is valuable for documentation pur¬ 
poses in that you can easily see the specific items that a 
client needs from the unit it uses. 

The following diagram explains the syntax of selective 
uses: 


^ USES 




In this diagram, ident can be a constant, type, variable, 
or routine (procedure, process, or function). Here is an 
example of a selective uses statement: 

USES MYUNIT (A CONST. VARl, VAR2, MY ROUTINE): 
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If a selected declaration is not present in the interface 
text, an error results during compilation. 

Any constant or type used in a selected declaration must 
be included in the selective uses list. For example, if 
VAR1 is of type TYPE1, the list above is not acceptable 
unless TYPE1 is added (even through TYPE1 may not be 
directly required by the client being compiled). 

You should list only the name of a routine. No explicit 
listing of parameters is needed. However, any types or 
constants that the parameters use must be explicitly 
included. 

Most identifiers must be named explicitly in the identifier 
list if they are to be made available to the compiled mod¬ 
ule. Identifiers are available implicitly in these situations: 

• When an enumerated constant type is explicitly 
listed, all the constant identifiers of the enumeration 
are implicitly available. 

• When a record type is explicitly listed, all its field 

names are implicitly available (for example, see the 
following listing under unit A, line 12, info_rec.) 
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Here is an example of selective uses. The first of these 
three compiled listings shows unit A, which is selectively 
used by units B and C. 


Pascal Compiler VERSION 1/1/83 Page 1 


1 

2 

l:d 

1 

unit A; 

2 

2 

l:d 

1 

interface 

3 

2 

l:d 

1 

const 

4 

2 

l:d 

1 

maxnum= 1000; 

5 

2 

l:d 

1 

maxchar=7; 

6 

2 

l:d 

1 


7 

2 

l:d 

1 

type 

8 

2 

l:d 

1 

byte=0..255; 

9 

2 

l:d 

1 

codeblock=packed array 
[0..maxnum] of byte; 

10 

2 

l:d 

1 

alpha = packed array 
[0..maxchar] of char; 

11 

2 

l:d 

1 

ptr_info_rec= info_rec; 

12 

2 

l:d 

1 

info rec=record 

it 

2 

l:d 

1 

code:codeblock: 

14 

2 

l:d 

1 

llink,rlink:ptr info 

15 

2 

l:d 

1 

end; 

16 

2 

l:d 

1 

next = char; 

17 

2 

l:d 

1 


18 

2 

l:d 

1 

var 

19 

2 

l:d 

1 

first. last:byte; 

20 

2 

l:d 

3 


21 

2 

l:d 

3 

function update(var info: ptr 
:next; 

22 

2 

l:d 

1 


23 

2 

l:d 

1 

implementation 

24 

2 

l:d 

1 


25 

2 

l:d 

1 

function update; 

26 

2 

2:0 

0 

begin 

27 

2 

2:1 

0 

with info A do 

28 

2 

2:2 

3 

begin 

29 

2 

2:3 

3 

llink = rlink; 

30 

2 

2:3 

12 

if rlink = llink then 

$i 

2 

2:4 

22 

update: = 'y' 

32 

2 

2:3 

22 

else 

33 

2 

2:4 

27 

update: = n'; 

34 

2 

2:2 

30 

end; 

35 

2 

1:0 

0 

end; 

36 

2 

1:0 

0 


97 

2 

:0 

0 

end. {unit A} 


End of Compilation. 
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1 

2 

l:d 1 

unit B; 

2 

2 

l:d 1 

interface 

3 

2 

l:d 1 

{$U a.code} 

4 

2 

l:d 1 

usesa( {const} maxchar, 

{include for type ALPHA} 

5 

2 

l:d 1 

{types} alpha, 

{include for variable WHICH} 

6 

2 

l:d 1 

byte, 

{include for FIRST and LAST} 

7 

2 

l:d 1 

{vars } first, 

{include for proc CHANGE} 

8 

2 

l:d 1 

last. 

{include for proc CHANGE} 

Using A 

• 

2 

l:u 1 


12 

2 

l:u 1 

maxchar = 7; 

15 

2 

l:u 1 

byte=0..255; 

17 

2 

l:u 1 

alpha=packed array 
[0..maxchar] of char: 

26 

2 

l:u 1 

first,last:byte; 

30 

2 

l:d 3 

); 

31 

2 

l:d 1 


32 

2 

l:d 1 

procedure change(which:alpha); 

33 

2 

l:d l 


34 

2 

l:d 1 

implementation 

35 

2 

l:d 


36 

2 

l:d 

procedure change: 

37 

2 

2:0 0 

begin 

38 

2 

2:1 4 

if which = ' 'then 

39 

2 

2:2 14 

last: = first 

40 

2 

2:1 14 

else 

■11 

2 

2:2 26 

first: = last: 

42 

2 

1:0 0 

end; 

43 

2 

1:0 0 


44 

2 

:0 0 

end; {unit B} 

45 

2 

:0 0 


46 

2 

:0 0 


47 

2 

1:0 0 

unit C: 

4§ 

2 

1:0 0 

interface 

m 

2 

1:0 0 

implementation 

50 

2 

1:0 0 

{$U a.code} 

11 

2 

1:0 0 

uses a( {const} maxnum, 

{include for type CODEBLOCK} 

52 

2 

1:0 0 

maxchar, 

{include for type ALPHA} 

53 

2 

1:0 0 

byte, 

{include for type CODEBLOCK} 

54 

2 

1:0 0 

{type} alpha, 

{include for variable MINE} 

55 

2 

1:0 0 

info__rec, 

{include for PTR„ INFO _REC} 




56 

2 

1:0 

0 

ptr_info_rec. 





{include for func UPDATE} 

57 

2 

1:0 

0 

codeblock. 





{include for INFO KEC} 

58 

2 

1:0 

0 

next. 





{include for func UPDATE} 




Using A 

59 

2 

1:0 

0 


|) 

2 

l:u 

1 

maxnum = 1000; 

62 

2 

l:u 

1 

maxchar=7; 

65 

2 

l:u 

1 

byte=0..255; 

m 

2 

l:u 

1 

codeblock=packed array 





[0..maxnumj of byte: 

67 

2 

l:u 

1 

alpha=packed array 





[0..maxcharJ of char; 

68 

2 

l:u 

1 

ptr _ info.. rec= A info _ rec; 

69 

2 

l:u 

1 

info. _rec = record 

70 

2 

l:u 

1 

code:codeblock; 

71 

2 

l:u 

1 

llink,rlink:ptr info_rec; 

72 

2 

l:u 

1 

end; 

73 

2 

l:u 

1 

next=char; 

78 

2 

l:u 

1 

function update 





(var info:ptr info rec):next; 

79 

2 

l:u 

3 


m 

2 

l:d 

3 

{func} update). 




Using B 

81 

2 

l:d 


b: 

82 

2 

l:d 



83 

2 

l:d 


var 

84 

2 

l:d 


info:ptr_info_rec; 

85 

2 

l:d 


mine:alpha; 

86 

2 

l:d 

0 


87 

2 

1:0 

0 

begin 

88 

2 

1:1 

0 

new(info); 

89 

2 

1:1 

7 

new(info A .rlink); 

90 

2 

1:1 

16 

info A .llink: = nil; 

91 

2 

1:1 

22 

mine: = 'newsystm'; 

92 

2 

1:1 30 

if update(info) = 'y' then 

93 

2 

1:2 39 

writeln('info updated') 

94 

2 

1:1 59 

else 

95 

2 

1:2 61 

change! mine): 

96 

2 

:0 

0 

end. 


End of Compilation. 




SEGMENTS, UNITS, AND LIBRARIES 


Segments, units, and libraries are three major facilities that help 
you manage large programs and effectively use main memory. 
These facilities enable very large programs to be developed in a 
microsystem environment; in fact, these facilities were used 
extensively in developing the system, itself. 

Segmenting a Program 

An entire program need not be in main memory at run¬ 
time. Most programs can be described in terms of a work¬ 
ing set of code that is required over a given time period. 
For most—if not all—of a program's execution time, the 
working set is a subset of the entire program, sometimes 
a very small subset. Portions of a program that are not 
part of the working set can reside on disk, thus freeing 
main memory for other uses. 

When the p-System executes a code file, it reads code into 
main memory. When the code has finished running, or the 
space it occupies is needed for some action having higher 
priority, the space it occupies can be overwritten with 
new code or new data. Code is swapped into main memory 
a segment at a time. 

In its simplest form, a code segment includes a main pro¬ 
gram and all of its routines. A routine can occupy a seg¬ 
ment of its own; this is accomplished by declaring it a 
segment routine. Segment routines can be swapped inde¬ 
pendently of the main program; declaring a routine a 
segment is useful in managing main memory. 

Routines that are not part of a program’s main working 
set are prime candidates for occupying their own seg¬ 
ment. Such routines include initialization and wrap-up 
procedures and routines that are used only once or only 
rarely while a program is executing. Reading a procedure 
in from a disk before it is executed takes time. Therefore, 
the way that you divide up a program is important. 
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UCSD Pascal, FORTRAN, and BASIC use their own 
syntax for creating separate segments. Refer to each par¬ 
ticular language’s manual for more information on this. 

Separate Compilation — Units 

Separate compilation is a technique whereby segments of 
a program are compiled separately and subsequently exe¬ 
cuted as a coordinated whole. 

Many programs are too large to compile within the mem¬ 
ory confines of a particular microcomputer. Such pro¬ 
grams might comfortably run on the same machine, 
especially if they are segmented properly. Compiling 
small pieces of a program separately can overcome this 
memory problem. 

Separate compilation also allows small portions of a pro¬ 
gram to be changed without necessarily affecting the rest 
of the code which saves time and is less error prone. 
Libraries of correct routines can be built up and used in 
developing other programs. This capability is important 
if a large program is being developed and is invaluable if 
the project involves several programmers. 

These considerations also apply to assembly language 
programs. Large assembly programs (such as p-machine 
emulators) can often be more effectively maintained in 
several separate pieces. When all these pieces have been 
assembled, the L(inker puts them together and installs 
the linkages that allow the various pieces to reference 
each other and function as a unified whole. 

You may also want to reference an assembly language 
routine from a Pascal host program. This may be neces¬ 
sary for performance reasons (assembly language is 
faster than p-code, the output of the compiler) or to pro¬ 
vide low-level, machine-dependent or device-dependent 
handling. 
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Using the L(inker, the p-System allows assembly lan¬ 
guage routines to be linked with other assembly routines 
or into higher-level clients (programs or units). For more 
information about this, see the UCSD p-System Assem¬ 
bler , TI Part Number 2232402-0001. 

In UCSD Pascal, separate compilation is achieved by the 
unit construct—a unit being a group of routines and data 
structures. The contents of a unit usually relate to some 
common application, such as display unit control or data 
file handling. A program or another unit may use the rou¬ 
tines and data structures of a unit by simply naming it in 
a USES declaration. The term host refers to such a pro¬ 
gram, and client compilation module refers to a program 
or unit that uses another unit. In addition to being a sepa¬ 
rately compiled module, a unit is also a code segment, in 
that it can be swapped—as a whole—in and out of mem¬ 
ory. You should note that it is possible for a unit’s source 
text to be embedded in the client’s source text if you do 
not want to compile a unit separately. 

A unit consists of two main parts: the interface section, 
which can declare constants, types, variables, procedures, 
processes, and functions that are public (available to any 
client module); and the implementation section (in which 
private declarations can be made). These private declara¬ 
tions are available only within the unit and not to client 
modules. 

Pascal, BASIC, and FORTRAN use their own syntax for 
separate compilation. (For more information about this, 
refer to each language’s manual.) 

Libraries 

This section describes where you may place the code files 
that contain units so those units are available at compile 
time or run time. Run time availability is described first. 
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There are four places where units can reside when the 
client’s code is executed: 

• Within your code file 

• In the SYSTEM.LIBRARY on the system disk 

• In a user library 

• In the operating system (SYSTEM.PASCAL) 

The operating system units (described in the next chap¬ 
ter) are standard code. Do not place units that you write 
there. The other three options are available for units that 
you write or use. 

In order to place a unit directly into a client’s code file, 
use the Library utility, described in the Utilities chapter. 
Once the unit’s code and your code are unified like this, 
the unit is available at run time. 

SYSTEM.LIBRARY generally contains standard units, 
such as the long integer package. You can add your units 
to this file with the Library utility. If you are not cur¬ 
rently using SYSTEM.LIBRARY, you can simply 
rename a unit’s code file SYSTEM.LIBRARY and place 
it on the boot disk. Of course, you can add more files with 
the Library utility. All units that reside in 
SYSTEM.LIBRARY are available to clients. 

A user library is any code file. The name of this code file 
must be in a library text file. The standard default library 
text file is called USERLIB.TEXT and must be on 
the system disk. For example, if you create a 
USERLIB.TEXT containing these lines: 

DISK2:SOME.UNITS 

♦MY.LIB 

ANOTHER.CODE 
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These three code files are designated as user libraries. 
You do not have to specify the .CODE here. For example, 
the first file may be either DISK2:SOME.UNITS.CODE 
or DISK2.SOME.UNITS, depending upon which file is 
actually found. All three of these files may contain units 
which are then available for clients to use. 

When the p-System is searching several libraries for a 
unit, it first searches all of the user libraries in the order 
that they appear in the default library text file. It then 
searches * SYSTEM. LIBRARY. If you wish to include 
*SYSTEM.LIBRARY in the library text file, it is 
searched in the order that it appears. (If no library text 
file is used, only *SYSTEM.LIBRARY is searched.) 

You can use a library text file other than 
USERLIB.TEXT. Do this with the L execution option. 
For example, if you select X(ecute from the command 
menu and respond: 

Executewhat fi l e 7 L=USERLIB2 


During compile time, as opposed to run time, the code for 
a unit can reside in either of two locations: 

• *SYSTEM.LIBRARY 

• A code file specified in the text you are compiling 

With UCSD Pascal, you indicate a specific code file using 
the $U (use library) compiler option which was described 
ear her. If you do not indicate a particular code file, the 
compiler searches *SYSTEM.LIBRARY for any units 
you want to use. If you do indicate a code file, the compi¬ 
ler looks there for the units. In the second case, if the 
unit is not found, the Pascal compiler searches 
*SYSTEM.LIBRARY, as well. 
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Pascal, BASIC, and FORTRAN each have a way to indi¬ 
cate the names of units that are to be used. Each lan¬ 
guage also has a method for specifying the code files that 
contain those units. If you do not indicate a particular 
code file, the compilers search *SYSTEM.LIBRARY for 
any units you want to use. If you do indicate a code file, 
the compilers look there for the units. In this second case, 
if the unit is not found, the Pascal Compiler searches 
♦SYSTEM.LIBRARY, as well. However, the BASIC and 
FORTRAN compilers only search that particular code 
file. (See the individual reference manuals for more infor¬ 
mation about this.) 


GENERAL TACTICS 

This section describes the use of segments and units. It presents 
a scenario for designing a large program, with some useful strate¬ 
gies. 

Units and segments divide large programs into independent 
tasks. On microprocessor systems, the main bottlenecks in devel¬ 
oping large programs are: 

• A large number of variable declarations that consume space 
while a program is compiling 

• Large pieces of code that use up memory space while the 
program is executing 

Units address the first problem by: allowing separate compila¬ 
tion; and minimizing the number of variables needed to communi¬ 
cate between separate tasks. Segments alleviate the second 
problem by only requiring code that is in use to be in main mem¬ 
ory at any given time; during this time, unused code resides on 
the disk. 
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You can write a program with run-time memory management and 
separate compilations already planned, or you can write the pro¬ 
gram as a whole and then break it into segments and units. The 
latter approach is feasible when you are unsure about having to 
use segments or quite sure that they will be used only rarely. The 
former approach is preferred and easier to accomplish. 

The following steps outline a typical procedure for constructing a 
relatively large application program: 

1. Design the program (user and machine interfaces). 

2. Determine needed additions to the library of units, both 
general and applied tools. 

3. Write and debug units and add to libraries. 

4. Code and debug the program. 

5. Tune the program for better performance. 

During design, try to use existing procedures to decrease coding 
time and increase reliability. You can accomplish this strategy by 
using units. 

To determine segmentation, consider the expected execution 
sequence and try to group routines inside segments so that the 
segment routines are called as infrequently as possible. 

While designing the program, consider the logical (functional) 
grouping of procedures into units. Besides making the compila¬ 
tion of a large program possible, this can help the program’s con¬ 
ceptual design and make testing easier. 

Units may contain segment routines. You should be aware that a 
unit occupies a segment of its own except, possibly, for any seg¬ 
ment routines it may contain. The unit’s segment, like other code 
segments, remains disk-resident except when its routines are 
being called. 
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Steps 2 and 3 of the typical construction procedure are aimed at 
capturing some of the new routines in a form that allows them to 
be used in future programs. At this point, you should review, and 
perhaps modify, the design to identify those routines that may be 
useful in the future. In addition, useful routines might be made 
more general and put into libraries. 

Program and test the Library routines before moving on to pro¬ 
gramming the rest of the program. This adds more generally use¬ 
ful procedures to the library. 

The interface part of a unit should be completed before the imple¬ 
mentation part, especially if several programmers are working on 
the same project. 

Tuning a program usually involves performance tuning. Since 
segments offer greater memory space at reduced speed, perfor¬ 
mance is improved by: turning routines into segment routines; or 
turning segment routines back into normal routines. Either route 
is feasible. Pay some attention to the rules for declaring seg¬ 
ments. 

For information on languages, refer to the appropriate language 
manual. 
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INTRODUCTION 


This chapter describes several facilities that can assist you in 
presenting a clean and portable user interface from your 
programs. 

The first section describes run-time facilities that enable you to 
create your own applications environment. The p-System can run 
invisibly under your application using these facilities. 

The next section describes the screen control unit. This unit, 
which is part of the operating system, can be used by your pro¬ 
grams to easily handle the basic screen-oriented functions (such 
as clearing the screen, moving the cursor, and so forth). 

Next, the error-handler unit is covered. It enables your programs 
to intercept certain kinds of system errors and display your own 
messages. You might want to do this so that the error messages 
are specific to your particular application, or so they are in a dif¬ 
ferent language, and so forth. 

After this, the command I/O unit is described. This unit allows 
you to redirect I/O and chain programs together. It is especially 
useful in conjunction with the run-time facilities in the first 
section. 

Finally, a couple of facilities for using the color and graphics 
capabilities of your Texas Instruments Professional Computer 
are covered. The first is a simple interface that your programs 
can use to change the screen colors, and so forth. The second is a 
much more comprehensive package called Turtlegraphics. 


RUN-TIME APPLICATION FACILITIES 


As an applications developer, you can create programs that are 
automatically executed by the p-System. This exempts the end- 
user from having to X(ecute these programs. The underlying 
p-System can even be completely hidden from such a user. You 
can present menus and prompts that apply specifically to your 
particular application. 
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If you name an executable code file SYSTEM.STARTUP and 
place it on the system disk, that program is executed when the 
p-System is booted. This program begins before the p-System’s 
command menu or welcome message is displayed. 

SYSTEM.MENU operates similarly. It is executed each time the 
command menu is normally displayed. 

Generally, SYSTEM.MENU is more useful for creating your own 
applications environments since it is called up repeatedly. 
Typically, you might place a simple menu-driven program in 
SYSTEM.MENU. This program displays the outer menus or 
prompts and services global issues related to your application 
package. When the user selects a component of your package, use 
the CHAIN procedure (within the operating system's Command 
I/O unit, described later in this chapter). CHAIN allows another 
program to execute (without using the X(ecute command or dis¬ 
playing the command menu in between). When that program 
completes its run, SYSTEM.MENU is again called. In this scena¬ 
rio, the p-System’s command menu never appears. 

The following diagram illustrates what happens when the 
p-System is initialized: 
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THE SCREEN CONTROL UNIT 


The screen control unit is a unit within the operating system that 
your programs can use to easily perform several useful screen- 
oriented tasks. These include blanking out a line or the entire 
screen, placing the cursor at a particular position, displaying 
p-System style menus, and so forth. These tasks are performed in 
a way that makes your programs transportable across different 
display units. 

You should realize that there is a special screen control unit for 
ANSI (American National Standards Institute) terminals. (These 
terminals use three character sequences. Most other terminals 
use, at most, two character sequences.) However, the interface 
section of this special version of the screen control unit is no dif¬ 
ferent from the standard unit. This means that your programs do 
not have to be changed. 

To use the screen control unit at compile time, you must have a 
copy of SCREENOPS.CODE with its interface section. A Pascal 
program must contain a USES declaration similar to this: 

USES {$U SCREENOPS.CODE} SCREENOPS: 

At run time, only the operating system needs to be available 
since it contains the SCREENOPS unit (without the interface 
section). 

SCREENOPS Interface Section 

Here is a listing of the interface section for 
SCREENOPS: 

unit screenops; 

interface 

const 

sc_fill_len =11; 

sc_eol =13; 

type 

sc chset = set of char; 

sc. misc_rec = packed record 

height, width: 0..255; 

can_ break, slow, xy _ crt, lc_crt, 

can_upscroll, can_downscroll: boolean; 
end; 
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sc date_rec = packed record 

month: 0..12; 
day: 0..31; 
year: 0..99: 

end; 

sc_info_type = packed record 

sc_ version: string; 
sc date; sc_ date_rec; 

spec ,char: sc_ chset; {Characters not to echo} 

misc _ info: sc_ misc_rec; 

end; 

sc _long_ string = string(255J; 

sc_scrn ^.command = (sc. .whome, sc_eras _ s, sc_ erase_eol, sc clear_lne, 

sc _ clear sen, sc _ up_cursor, sc_down_cursor, 

sc _left_ cursor, sc_right_cursor); 

sc key command = (sc backspace^ key.se del key, 

sc eof_ key, sc etx key, sc escape key, sc del key, 

sc up_key, sc down key, sc left_key, sc__right key, 

sc not .legal, sc_ insert key, sc_ delete key); 

sc_choice = (sc_get, sc _ give); 

sc window = packed array [0..0] of char; 

sc _ tx_port = record 

row, col, { screen relative} 

height, width, { size of txport (zero based)} 

cur _ x, cur _ y : integer; 

{cursor positions relative to the txport } 

end; 

{entries 4..syscorn .subsidstart—1 are valid} 
sc err_ msg array = array [4..4] of string; {accessed $R—} 

var 

sc_port: sc_ tx port; 

sc printable chars: sc chset; 

sc errorline: integer; 

sc errormessage: sc err_msg_ array; 

procedure sc_use_info(do what:sc_choice; vart_info:sc_info_type); 

procedure sc use port(do what:sc choice; vart port:sc _ tx_port); 

procedure sc_erase to_ eol(x,line:integer); 

procedure sc left; 

procedure sc. right; 

procedure sc_up; 

procedure sc_down; 

procedure sc getc ch(var ch:char; return_on matchisc chset); 

procedure sc _ clr_screen; 

procedure sc . clr _ line (y:integer); 

procedure sc _ home; 

procedure sc eras, eos (x,line:integer); 

procedure sc __goto _ xy(x, line:integer); 

procedure sc _ clr _ cur_line; 

function sc_find. _*:integer; 
function sc_find, yrinteger; 

function sc_scrn_has(what:sc_scrn _ command):boolean; 

function sc_has_key(what:sc_key_command):boolean; 
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function sc_map_crt command!var k _ ch:char):sc _ key_command; 

function sc_prompt!line :sc Jong _ string; x_cursor,y_cursor,x_pos, 

whereiinteger; retum_on_match:sc__chset; 

no _ char backiboolean; break_char:char):char; 

function sc check_char!var bufisc window; var buf _ index,bytes_Jeft;integer) 

iboolean; 

function sc space_wait(flush:boolean):boolean; 

procedure sc_init; 


Routines within SCREENOPS 

This section describes the routines within the screen con¬ 
trol unit. The text ports mentioned here are rectangular 
portions of the screen that may be defined as smaller than 
the real screen. At present, this feature is not fully 
implemented. Where text ports are mentioned in this sec¬ 
tion, the entire screen is the default. 

Procedure SC_Init; 

Usually, only the operating system calls this procedure. 
It initializes all the screen control tables and variables. 

Procedure SC_Clr_Cur_Line; 

Erases the current line. 

Procedure SC_Clr_Line ( Y: integer); 

Clears line number Y within the current text port. 

Procedure SC_Clr_Screen; 

Clears the screen. 

Procedure SC_Erase_to_EOL 

( X, Line: integer); 

Starting at position (X, Line) within the current text port, 
erases everything to the end of the line. 
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Procedure SC_Eras_EOS 

( X, Line: integer); 




Starting at position (X, Line) within the current text port, 
erases everything to the end of the screen. 

Procedure SC_Left; 

Moves the cursor one character to the left. 

Procedure SC_Right; 

Moves the cursor one character to the right. 

Procedure SC_Up; 

Moves the cursor one line up (in the same column). 

Procedure SC_Down; 

Moves the cursor one line down. 

Procedure SC_Home; 

Moves the cursor to position 0,0 within the current text 
port. 

Procedure SC_GOTO_XY 
( X, Line: integer); 

Moves the cursor to position (X, Line). 

Function SC_Find_X: integer; 

Returns the column position of the cursor, relative to the 
current text port. 

Function SC_Find_Y: integer; 

Returns the row position of the cursor, relative to the cur¬ 
rent text port. 


3-9 




Procedure SC_GetC_CH 

(VAR CH: char; 

Return_on_Match: SC_ChSet); 

SC_ChSet is a SET OF CHAR. This procedure re¬ 

peatedly reads from the keyboard into CH until CH is 
equal to a member of Return_on_Match. The charac¬ 

ters that you pass in this set should all be capitals (if they 
are alphabetic). If a lowercase alphabetic character is 
received from the keyboard, it is translated into upper¬ 
case before it is compared to the characters within 
Return_on_M atch. 

Function SC_Space_Wait 

( Flush: Boolean): Boolean; 

This function repeatedly reads from the keyboard until a 
space or the ALTMODE character is received. Before 
doing this, it does a UNITCLEAR(l) if flush is true, and 
displays Type<space> to continue - It returns 
true if a space was not read. After reading a space suc¬ 
cessfully, this function executes a carriage return on the 
console. 

FUNCTION SC_Prompt 

( Line: SC_Long_String; 

X_Cursor, Y_Cursor, X_Pos, 

Where: integer; 

Return_on_Match: SC_ChSet; 

No_Char_Back: Boolean; 

Break_Chair: char): char; 




This function displays the menu line (SC_Long_String 

is a STRING [255]) in the current text port at (X_Pos, 

Where). The cursor is placed at (X_Cursor, Y_Cursor) 

after the prompt is printed. If X_Cursor is less than 0, 

the cursor is placed at the end of the prompt. If the 
prompt is too large to fit within the current text port, it is 
broken up into several pieces, but only at the 

Break_Char. You can view different parts of the prompt 

(cycling through them) by pressing a question mark (?). If 

you only want to display the prompt, NO_Char_Back 

should be true. (In this case, SC_Prompt returns a func¬ 

tion value of NUL, ASCII 0.) If you want to receive 
a character from the user at the keyboard, 

NO_Char_Back should be false. (In this case, 

SC_Prompt returns a function value of the character 

received.) The keyboard is repeatedly read until the char¬ 
acter read matches one within the Return_on_Match 

set. (All alphabetic characters in this set should be 
capitals.) 

FUNCTION SC_Check_Char 

( VAR Buf: SC_Window; 

VAR Buf_Index, 

Bytes_Left: integer): Boolean; 

While a string is being read, this function can be called to 
see if a backspace or a rubout (DEL) has been read. If so, 
the input buffer is altered accordingly, and true is 

returned. Buf is a line on the screen, Buf_Index indicates 

the cursor position within Buf, and Bytes_Left is the 

number of characters to the right of the cursor. 

Function SC_Map_CRT_Command 

( VAR K_CH: char): 

SC_Key_Command; 
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SC_Key_Command is a type consisting of the following 

elements. (SC Backspace Key, SC DC1 Key, 

SC_EOF_Key, SC_ETX_Key, SC_Escape_Key, 

SC_DEL_Key, SC_Up_Key, SC_Down_Key, 

SC Left Key, SC Right Key, SC Not Legal, 

SC_Insert_Key, SC_Delete_Key). The character 

passed is mapped into one of these elements. 

SC_Not_Legal is where all characters are mapped that 

do not fit into one of the other ten categories. Prefix char¬ 
acters are recognized by this function. If you pass a prefix 
character, a non-echoed read is done to get the next char¬ 
acter (before the mapping is performed). In this case, 
K_CH is returned as that character. For the ANSI ver¬ 

sion of Screenops, yet another read can be done (since 
three character codes are used on ANSI terminals). 

Function SC_Scrn_Has 

( What: SC_Scrn_Command ): 

Boolean; 

SC_Scrn_Command is a type consisting of the 

following elements. (SC_Home, SC_Eras_S, 

SC_Eras_EOL, SC_Clear_Lne, SC_Clear_Sen, 

SC_Up_Cursor, SC_Down_Cursor, 

SC_Left_Cursor, SC_Right_Cursor.) This function 

returns TRUE if the keyboard has the control character 
passed. 

Function SC_Has_Key 

( What: SC_Key_Command ): 

Boolean; 

SC_Key_Command consists of the elements previously 

listed in the description of SC_Map_CRT_Command. 

This function returns true if the keyboard generates the 
character passed. 

Procedure SC_Use_Info 

( Do_What: SC_Choice; 

VAR T_Info: SC_Info_Type); 
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This function is used to pass information back and forth 
between a program and the screen control unit. 
Do_What may either be SC_Get or SC_Give and indi¬ 

cates whether the program is getting information from 
the screen control unit or giving information to it. 

T_Info contains various items to be either passed or 

received. The following information is contained within 
T_Info. 

SC _ Version: string; 

SC _ Date: PACKED RECORD 

Month: 0..12; 

Day: 0..31; 

Year: 0..99; 

END; 

Spec _Char: SET OF char; (* Characters not to echo *) 

Misc _ Info: PACKED RECORD 

Height. Width: 0..255; 

Can Break, Slow. XY_CRT, LC_CRT, 

Can__UpScroll, Can_DownScroll: Boolean; 

END; 


Procedure SC_Use_Port 

( Do_What: SC_Choice; 

VAR T_Port: SC_TX_Port); 

This function works like SC_Use_Info above. The con¬ 
tents of T_Port are either passed or received from the 

screen control unit. T_Port contains the following infor¬ 

mation. 

Row, Col, 

Height, Width, 

Cur_X, Cur_Y : integer; 
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ERROR HANDLER UNIT 


Under certain circumstances, the p-System displays execution 
error messages. If a code segment is needed and the disk contain¬ 
ing it is not in the appropriate drive, you are asked to replace the 
disk and press the space bar to continue. If a program attempts 
to divide by zero or access outside the bounds of a Pascal array, a 
message indicates this and the user is asked to press the space 
bar, at which point the p-System is reinitialized. 

When certain errors occur, your programs can alter the message 
that is displayed. This is useful for applications developers, 
especially those whose customers speak languages other than 
English. 

Format of Error Messages 

Error messages are displayed on one specified 80-column 
line. For example, when a code segment is needed from a 
disk that is not present in the appropriate drive, the fol¬ 
lowing prompt is displayed. 


Need segment SEGNAME: Put volume VOLNAME in unit U then 
press <space> 


This indicates that the segment SEGNAME was not 
found on the volume in device U. Place the volume 
VOLNAME in the correct drive and press the space bar. 
Execution should continue normally. 

The following example shows the error message that 
occurs when a user presses the p-System BRK (Break) 
key. BRK is a shifted version of the BRK/PAUSkey. 

Program Interrupted by user-Seg PASCALIO P# 17 0# 310 
<space> continues 

After the space bar is pressed, the p-System is reinitial¬ 
ized. 
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System error messages, such as these, always appear at a 
fixed position on the display unit. The default position is 
the bottom line. (Any line can be specified, however.) 
A BEL character (audible beep) is written to the console 
device when the message is written out. 

After pressing the space bar, the message line disap¬ 
pears, and when possible, the cursor returns to its pre¬ 
vious position. If a program uses UNITREADs or 
UNITWRITEs to the console, the previous cursor posi¬ 
tion may be lost. This is because the p-System is not 
informed of the cursor position after these kinds of low 
level I/O operations. 

User Control of Error Messages 

Your program may change the line on which an error 
message is displayed. It may also change the actual mes¬ 
sage displayed when a code segment is required from a 
disk that is not present in the appropriate drive for 
blocked devices. If the code file is on a subsidiary volume, 
set the message for the principal volume. 

The ERRORHANDLING unit provides these facilities. 
The file ERRORHAND.CODE contains this unit. To use 
ERRORHANDLING, a Pascal program should have a 
declaration similar to the following example. 

{$U ERRORHAND.CODE} ERRORHANDLING; 

Also, ERRORHANDLING must be available at run 
time, either in a library or placed into the using program's 
code file with the Library utility. 
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The following procedures are available within this unit: 

Procedure Set_Error_Line 

(Line:integer); 

Procedure Set_User_Message 

(driverinteger; 
mesg: string); 

By calling SET_ERROR_LINE with the desired line 

number as a parameter LINE, your program may change 
the line on which p-System run-time error messages are to 

be displayed. After the call to SET_ERROR_LINE, 

any run-time error messages are displayed on that line 

until SET_ERROR_LINE is used again to specify 

another line. 

You can change the standard message for code seg¬ 
ments needed on disks that are not present. Call 

SET_USER_MESSAGE with the DRIVE parameter 

set to the physical device number and the MESG parame¬ 
ter set to the desired message string. 

Then, if a code segment is required from a missing disk in 
the unit for which the user program has designated a 
special error message, that message is displayed. The 
p-System then waits for the user to press the space bar, 
whether or not your message actually indicates that a 
space is needed. The message line is subsequently erased; 
the cursor returns to its former position, if possible; and 
execution continues. 


CAUTION 

A user message is destroyed if a MARK is 
called before a SET_USER_MESSAGE. 

NOTE 

The physical device numbers are #4, #5, and #9 
through the maximum number for physical 
disks as configured in SETUP. 



For other kinds of execution errors, a standard p-System 
message is displayed on the message line. A fatal error 
always causes the p-System to fail. For nonfatal errors, 
the p-System waits for the user to press the space bar. 
The message line is then erased, the cursor returns to its 
former position, and execution continues (most likely the 
p-System reinitializes itself). 

To proceed from a nonfatal error, press the ESC key. 
CAUTION 

Escaping from a nonfatal error is a dangerous 
practice since system data may be corrupted. 

Error message values that you set remain in effect during 
the program run, but are reset at program termination or 
whenever p-System reinitialization occurs. 

Your program may reset the error handling values to 
their default values at any time if special output is 
no longer desired. The missing code segment message 
can be reset by passing a null string to 
SET_USER_MESSAGE. 

Unknown results may occur on console devices whose 
display unit width is narrower than the message to be 
displayed. 


THE COMMAND I/O UNIT 

Command I/O is a unit in the operating system. From Pascal, 
your program should contain the statement: 


USES {$U commandio.code} COMMANDIO; 


3-17 







Then, the following procedures are available to the program: 

Procedure Chain 

( Exec_Options: String); 

A call to CHAIN causes the system to X(ecute 
EXEC_OPTIONS after the calling program (the chaining pro¬ 

gram) has terminated. The effect is that of: manually pressing X 
to call Xfecute; and entering the characters in 

EXEC_OPTIONS. Neither the command menu nor the X(ecute 

prompt is displayed; the system goes on to immediately perform 
the actions indicated by EXEC_OPTIONS. 

If a program (or sequence of programs) contains more than one 

call to CHAIN, the EXEC_OPTIONS are saved in a queue and 

performed on a first-in-first-out basis before returning control of 
the system to you. 

To clear the queue, call CHAIN with an empty string (for exam¬ 
ple, CHAIN();). 

An execution error or an error in an EXEC_OPTIONS string 

clears the queue, returning control to the user. A call to 
EXCEPTION, described below, may also clear the queue. 

CHAIN is a procedure in the operating system's COMMANDIO 
unit; to use it, a program or unit must declare USES 
COMMANDIO. 

Function Redirect 

( Exec_Options: String): Boolean; 

This should contain only option specifications and not the name 
of a file to execute (to execute a program from another program, 
see the CHAIN intrinsic). 

REDIRECT causes redirection by performing all the options 

specified in EXEC_OPTIONS. If all goes well, it returns true. If 

an error occurs, it returns false. 
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If an error occurs during a call to REDIRECT, the state of 
redirection is indeterminate; this is a dangerous condition. If 
REDIRECT returns false, the user’s program should follow it 
with a call to EXCEPTION in order to turnoff all redirection. If 
the user does not do this, the results are unpredictable. 

REDIRECT is a procedure in the operating system’s 
COMMANDIO unit; to use it, a program or unit must contain 
the declaration USES COMMANDIO . 

Procedure Exception 

(Stopchaining: Boolean); 

EXCEPTION turns off all redirection. If STOPCHAINING is 

true, then the queue of EXEC_OPTIONS created by CHAIN is 

also cleared (see the intrinsic CHAIN). 

Whenever an execution error occurs, an EXCEPTION(TRUE) 
call is made (leaving redirection on after an error would leave the 
system in an indeterminate state). 

EXCEPTION is a procedure in the operating system’s 
COMMANDIO unit; to use it, a program or unit must declare 
USES COMMANDIO . 


3-19 




SIMPLE COLOR INTERFACE 


The p-System on the Texas Instruments Professional Computer 
provides a simple interface to assist you in utilizing the special 
features of the color and grey scale display unit. The following 
table defines the character attribute set: 


Character Attributes Set 


Attribute 

COLOR/INTENSITY 

ENABLE 

REVERSE VIDEO 

BLINK 


Description 

Defines the color of subsequent output when 
the color display unit is installed or the inten¬ 
sity of output when the gray scale display 
unit is used (default white) 

Defines whether or not subsequent output 
will be displayed on the display unit (default 
display enabled) 

Defines whether background or foreground 
is to be highlighted (default not underlined) 

Defines whether characters displayed will be 
underlined (default not underlined) 


ALTE RNATE Defines whether character fonts 

CHARACTER SET will be defined by the primary or alternate 

character set (default primary) 


NOTE 

You should realize that more than one attribute may 
be specified but that certain combinations will not 
make sense. For example, if character enable is false, 
then output does not appear nor do any of the other 
attributes except for reverse video. 
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The next table lists special characters that you can send to the 
display unit using the UNITWRITE intrinsic from a Pascal 
program. (You should see UCSD Pascal , TI Part Number 
2232401-0001, for information about UNITWRITE.) Each of 
these codes must be preceded (or prefixed ) by the ASCII ESC 
character, decimal 27. 


Attribute Character Sequences 


Character 

Attribute Toggled 

Description 

81 

GLOBAL Enable 

Changes the attribute of each 
displayed character to the most 
recently defined attribute. 

82 

BLACK Enable 

Enables BLACK (no output) 

83 

BLUE Enable 

Enables BLUE output 

84 

RED Enable 

Enables RED output 

85 

GREEN Enable 

Enables GREEN output 

86 

CYAN Enable 

Enables BLUE-GREEN output 

87 

YELLOW Enable 

Enables RED-GREEN output 

88 

MAGENTA Enable 

Enables BLUE-RED output 

89 

WHITE Enable 

Enables WHITE output 

90 

CHARACTER Enable 

When character enable is active 
(true) characters are displayed on 
the display unit when output. 
When false, characters will not be 
displayed on the display unit 

91 

REVERSE VIDEO 
TOGGLE 

Toggles REVERSE VIDEO 
background/foreground 

92 

UNDERLINE TOGGLE 

Toggles UNDERLINING of 
characters displayed 

93 

BLINK TOGGLE 

Toggles BLINKING of charac¬ 
ters displayed 

94 

ALTERNATE CHAR 

SET 

Enables/disables the ALT 
character set for output 

95 

GLOBAL RESET 

RESETs all attributes to the sys¬ 
tem defaults 
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Sequences that enable functions OR an attribute with the pre¬ 
vious attribute set. Sequences that toggle functions XOR an 
attribute with the previous value of the attribute and then OR 
the new attribute value into the attribute set. Simply put, toggles 
turn attributes on the first time they are output and off the next 
time they are output. Sequences that enable attributes always 
turn those attributes on. Defining a new attribute does not affect 
the remainder of the attribute set (that is, changing color does not 
affect whether or not the character is displayed with an under¬ 
line). 

Although these sequences provide a simple interface to the color 
capabilities of the high resolution color graphics monitor, the 
Turtlegraphics package, described later, is available to provide 
more comprehensive access to the capabilities of the system con¬ 
sole. 

There are some special keys described in Appendix A which are 
related to display intensity, color, cursor appearance, and so 
forth. 


TURTLEGRAPHICS 

Turtlegraphics is a package of routines for creating and manipu¬ 
lating images on your Texas Instruments Professional Com¬ 
puter’s display unit. These routines can be used to control the 
background of the display unit, draw figures, alter old figures, 
and display figures using viewports and scaling. Turtlegraphics 
also contains routines that allow you to save figures in disk files 
and retrieve them. 

The simplest Turtlegraphics routines are intentionally very easy 
to learn and use. Once you are familiar with these, more compli¬ 
cated features (such as scaling and pixel addressing) should pre¬ 
sent no problem. 

A pixel is a single picture element or point on the display. 
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Turtlegraphics allows you to create a number of figures or draw¬ 
ing areas, such as the display unit. Other figures can be saved in 
memory. Each figure has a turtle of its own. You can set the size 
of a figure (it does not need to be the same size as the actual dis¬ 
play). 

The actual display is addressed in terms of a display scale, which 
can be set by you. This allows your own coordinates to be mapped 
into pixels on the display. All other figures are scaled by the 
global display scale. 

You can also define a viewport, or window on the display. This 
limits all graphic activity to within that port. 

In order to use Turtlegraphics, your Pascal programs must 
include a uses statement like this: 


USES Turtlegraphics; 


Each subsection below is divided into two parts. The first part is 
an overview of the topic at hand, and the second part consists of 
descriptions of the relevant Turtlegraphics routines. 

The Turtle 

The turtle is an imaginary creature in the display screen 
that draws lines as your program moves it around the 
display. The turtle can move in a straight line (Move), 
move to a particular point on the display (Moveto), turn 
relative to the current direction (Turn), and turn to a par¬ 
ticular direction (Turnto). 

Thus, the turtle draws straight lines in some given 
direction. The color of the lines it draws can be specified 

(Pen_color) and so can the nature of the line drawn 

(Pen_mode). 

Wherever the turtle is located, its position and direction 

can be ascertained by three functions: Turtle_x, 

Turtle_y, and Turtle_angle. 
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NOTE 


The turtle may be moved anywhere; it is not 
limited by the size of the figure or the size of 
the display. But, only movements within the 
figure are visible. 

To use the turtle in a figure other than the actual display, 
you may call Activate_Turtle. 

The following paragraphs describe the routines that con¬ 
trol the turtle. 

Procedure Move (distance: real); 

Moves the active turtle the specified distance along its 
current direction. The turtle leaves a tracing of its path 
(unless the drawing mode is nop). The distance is speci¬ 
fied in the units of the current display scale (see below). 
The movement is visible unless the current turtle is in a 
figure that is not currently on the display. 

Procedure Moveto (x,y: real); 

Moves the active turtle in a straight line from its current 
position to the specified location. The turtle leaves a trac¬ 
ing of its path (unless the drawing mode is nop). The x,y 
coordinates are specified in the units of the current dis¬ 
play scale. 

Procedure Turn (rotation: real); 

Turns the active turtle by the amount specified (in 
degrees). A positive angle turns the turtle counterclock¬ 
wise, and a negative angle turns it clockwise. 





Procedure Turnto (heading: real); 

Sets the direction (the heading) of the active turtle to a 
specified angle. The angle is given in degrees; zero (0) 
degrees faces the right side of the screen, and ninety (90) 
degrees faces the top of the screen. 

Procedure Pen_color (shade: integer); 

Selects the color with which the active turtle traces its 
movements (unless the pen mode is nop). This color 
remains the same until Pen_color is called again. 

Here are the colors that correspond to the shade number: 

0 = Black 

1 = Blue 

2 = Red 

3 = Magenta 

4 = Green 

5 = Cyan 

6 = Yellow 

7 = White 


The term wild card refers to the standard background 
color of your display. This depends on your display hard¬ 
ware, and might be called a hard background (you may or 
may not be able to change it from a program; this 
depends on your hardware configuration). In Turtle- 
graphics, each individual figure may have its own soft 
background color, which we refer to simply as the back¬ 
ground color (as in the discussion below). 

You may also use black and white graphics, in which case 
the colors might be simply: 

0 = Black 
1 = White 
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Procedure Pen_mode (mode: integer); 

Sets the active turtle’s drawing mode. This mode does 
not change until Pen_mode is called again. 

These are the possible modes: 

0 = Nop — does not alter the figure. 

1 = Substitute — writes the current pen color. 

2 = Overwrite — writes the current pen color. 

3 = Underwrite — writes the current pen color. When 

the pen crosses a pixel that is not of the back¬ 
ground color, that figure is not overwritten. 

4 = Complement — the pen complements the color of 

each pixel that it crosses. (The complement of a 
color is its opposite: the complement of the com¬ 
plement of a color is the original color.) 

Values greater than four are treated as Nop. 

These descriptions apply to movements of the turtle. 
They have a more complex meaning when a figure is 
copied onto a figure that is already displayed. 

Function Turtle_x : real; 

Returns a real value that is the x-coordinate of the active 
turtle, in units of the current Display_scale. 

Function Turtle_y : real; 

Returns a real value that is the y-coordinate of the active 
turtle, in units of the current Display_scale. 

Function Turtle_angle : real; 

Returns a real value that is the direction (in degrees) of 
the active turtle. 
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Procedure Activate_Turtle 

(screen: integer); 

Specifies to which figure subsequent Turtlegraphics 
commands are directed. Each invocation of this pro¬ 
cedure puts the previously active turtle to sleep and 
awakens the turtle in the designated figure. When Turtle- 
graphics is initialized, the turtle in the actual display is 
awake. The initial position of the turtle is (0,0) or the bot¬ 
tom left corner of the display unit, ready to move right. 

The Display 

We refer to the initial background of the display as the 
wild card color. The wild card color (color 0) depends on 
your hardware (or it may be possible for you to set it from 
a program). The default is typically black. The back¬ 
ground color of a Turtlegraphics figure may be changed 
by you with a call to background. This soft background 
applies when the drawing mode is used, as indicated 
above. 

A figure can be filled with a single color (not necessarily 
the background color) by calling Fillscreen. 

NOTE 

If you use Turtlegraphics (or customized rou¬ 
tines of your own) to alter the settings of your 
display, it is a good idea to reset everything 
before your program terminates. Usually it is 
not possible for the display to return to its orig¬ 
inal state, and the p-System software has no 
knowledge of what that original state was. 
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Procedure Fillscreen 

(screen: integer; shade: integer); 

Fills the specified figure ( screen ) with the specified color 
(shade). If screen = 0, which indicates the actual display 
unit, then only the current viewport is shaded. For user- 
created figures, the entire figure is shaded. 

Procedure Background 

(screen: integer; shade: integer); 

Specifies the background color for a figure. The initial 
background color of all figures is the wild card color. 

Labels 


It is possible to draw legends, labels, and so forth on the 
display while using the Turtlegraphics unit. This is done 
by calling either WChar or WString. The character or 
string appears at the location of the currently active tur¬ 
tle. The text is displayed in the type font defined by the 
file *SYSTEM.FONT. 

Procedure WChar 

(c: char; copymode, shade: integer); 

Writes a single character at the position of the currently 
active turtle, using the indicated pen mode and color. The 
character is always displayed horizontally, regardless of 
the active turtle's direction. 

Procedure WString 

(s: string; copymode, shade: integer); 

Writes a string starting at the position of the currently 
active turtle, using the indicated pen mode and color. The 
string is always displayed horizontally, regardless of the 
active turtle’s direction. 
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Scaling 


When you wish to display data without altering the input 
data itself, it is possible to set scaling factors that trans¬ 
late data into locations on the display. This is done with 

Display_scale. The display scale applies globally to all 

figures. 

Because of the shape of the actual display, data for partic¬ 
ular shapes (especially curved figures) might become dis¬ 
torted when using a straight display scale. In this case, 

the function Aspect_ratio can be used to preserve the 

squareness of the figure. 

Procedure Display_scale 

(min_x, min_y, max_x, max_y: real); 

Defines the range of input coordinate positions that are 
to be visible on the display. Turtlegraphics maps your 
coordinates into pixel locations according to the scale 
specified in Display_scale. 

This procedure sets the viewport to encompass the whole 
display. The display bounds apply to input data. For the 
actual display, these bounds can be any values you 
require, but for user-created figures (0,0) is the lower left- 
hand corner. 

If your Turtlegraphics package is tailored to your hard¬ 
ware, then the default display scale is already supplied. If 
you purchased Turtlegraphics as a separate, configurable 
product, then you must supply the parameters for your 
own display (these must be returned by the user-written 
procedure Query_Environment). 

The following lines are an example of a default scale. It is 
simply the array of pixels on the FULL display. 


min_x = 0, max_x = 319 

min_y = 0, max_y =199 
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As an example, if you wish to graph a financial chart from 
the years 1970 to 1980 along the x axis, and from 500,000 
to 500,000,000 along the y axis, the following call could 
be used. 


Display _ scale! 1970, 5.0E5, 1980, 5.0E8) 


After this, calls to turtle operations could be done using 
meaningful numbers rather than quantities of pixels. 

Function Aspect_ratio : real; 

Returns a real number that is the width/height ratio of 
the display unit. This can be used to compute parameters 
for Display_Scale that provide square aspect ratios. 

If an application is designed to show information where 
the aspect ratio of the display is critical (for example, cir¬ 
cles, squares, pie-charts, and so forth) it must insure that 
the following ratio is the same as the aspect ratio of the 
physical display unit upon which the image is displayed. 


(max_x — min_x) / (max_y — min_y) 


When the Turtlegraphics unit is initialized, min_x and 

min_y are set to zero. Max_x is initialized to the num¬ 

ber of pixels in the x direction, and max_y is initialized 
to the number of pixels in the y direction. In order to 
change to different units that still have the same aspect 
ratio, use a call similar to the following example. 


Display_scale(0, 0. 100*ASPECT RATIO, 100); 


This utilizes Function Aspect_ratio described above, 

and makes the y axis 100 units long. 
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Turtlegraphics always treats the turtle as being in a fixed 
pixel location. Changing the scaling of the system with a 
call to this routine in the middle of a program does not 
alter the pixel position of any of the turtles in the figures. 

However, the values returned from X_pos and Y_pos 

may change. 

Figures and the Port 

You can create and delete new figures, each with its own 
turtle. When a new figure is created, it is assigned an inte¬ 
ger, and this integer refers to that figure in subsequent 
calls to Turtlegraphics procedures. New figures can be 

saved (Put_Figure) or displayed on the display unit 

(Get_figure). 

The actual display is always referred to as figure 0. 

The active portion of the display can be restricted by call¬ 
ing viewport, which creates a window on the display unit 
in which all subsequent graphics activity takes place. 
You can create a figure, specify the port, then display 
that figure (or a portion of it) within the port. Specifying a 
viewport does not restrict turtle activity, it merely 
restricts what is displayed on the display unit. 

User-created figures can be saved in p-System disk files. 

Function Create_Figure 

(x_size,y_size: real): integer; 
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Creates a new figure that is rectangular, and has the 

dimensions (x_size, y_size), where (0,0) designates the 

lower left-hand corner. The dimensions are in units of the 
current display scale. The figure is identified by the inte¬ 
ger returned by Create_figure. 

When a figure is created, it contains its own turtle; which 
is located at the initialization position or 0,0 and has a 
direction of 0 (it faces the right-hand side of the figure). 
The turtle in a user-created figure can be used by calling 
Activate_Turtle. 

Procedure Delete_figure 

(screen: integer); 

Discards a previously created display figure area. 

Though figures may be created and destroyed, indiscrimi¬ 
nate use of these constructs may rapidly exhaust the 
memory available in the p-System due to heap fragmenta¬ 
tion. For example, a figure can be created using 
Create_Figure (or it can be read in from disk using Func¬ 
tion Load_Figure, described below). If possible, after 

that figure is used (for example, with a Get_Figure, 

Put_Figure, Load_figure or Store_Figure operation) it 

should be deleted before other figures are created. If 
many figures are created and randomly deleted, the heap 
fragmentation problem may occur. 

Procedure Get_Figure 

(source_screen: integer; 

corner_x,corner_y: real; mode: integer); 

Transfers a user-created figure (the source) to the display 
unit (the destination) using the drawing mode specified. 
The figure is placed on the display such that its lower left 

corner is at (corner_x, corner_y). The x and y positions 

are specified in the units of the current display scale. If 
the display scale has been modified since the figure was 
created, the results of this procedure are unpredictable. 
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The following items define the drawing mode numbers. 

0 Nop. Does not alter the destination. 

1 Substitute. Each pixel in the source replaces the 
corresponding pixel in the destination. 

2 Overwrite. Each pixel in the source that is not of 
the source's background color replaces the corre¬ 
sponding pixel in the destination. 

3 Underwrite. Each pixel in the source that is not of 
the source’s background color is copied to the corre¬ 
sponding pixel in the destination only if the corre¬ 
sponding pixel is of the destination’s background 
color. 

4 Complement. For each pixel in the source that is 
not of the source’s background color, the corre¬ 
sponding pixel in the destination is complemented. 

Values greater than four are treated as Nop. 

If a portion of the source figure falls outside the display 
or the window, it is set to the source’s background color. 

Procedure Put_Figure 

(destination_screen: integer; 

corner_x,corner_y: real; mode: integer); 

Transfers a portion of the display unit to a user-created 
figure using the drawing mode specified (see above). The 
portion transferred to the figure is the area of the display 
that is covered when the figure is placed on the display 

with its lower left-hand corner at (corner_x, corner_y). 

If the display scale has been modified since the figure was 
created, the results of this procedure are unpredictable. 
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NOTE 


When a figure is moved to the display by 
Get_Figure, further modifications to the dis¬ 

play do not affect the copy of the figure that is 
saved in memory. If you wish to save the 
results of graphics work on the display, you 
must call Put_Figure. 

Procedure Viewport 

(min_x,min_y, max_x,max_y: integer); 

Defines the boundaries of a window that confines subse¬ 
quent graphics activities. The viewport procedure applies 
only to the actual display. When a window has been 
defined, graphics activities outside of it are neither dis¬ 
played nor retained in any way. Therefore, lines, or por¬ 
tions thereof, that are drawn outside the window are 
essentially lost and are not displayed (this is true even if 
the window is subsequently expanded to encompass a 
previously drawn line). The viewport boundaries are spec¬ 
ified in the units of the current display scale. If the speci¬ 
fied size of the viewport is larger than the current range 
of the display, the viewport is truncated to the display 
limits. 


Pixels 


It is possible to ascertain (Read_pixel) or alter 

(Set_pixel) the color of an individual pixel within a given 

figure. These routines are more specific than the turtle- 
moving routines. They are less straightforward to use, 
but give you greater control. 

Function Read_pixel 

(screen: integer; x,y: real): integer; 

Returns the value of the color of the pixel at the x,y loca¬ 
tion in the specified figure. The x,y location is specified in 
the units of the current display scale. 
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Procedure Set_pixel 

(screen: integer; x,y: real; 
shade: integer); 

Sets the pixel at the x,y location of the specified figure to 
the specified color. The x,y location is specified in the 
units of the current display scale. 

Fotofiles 

You can create disk files that contain Turtlegraphics fig¬ 
ures. New figures can be written to a file, and old figures 
restored for viewing or modification. 

When figures are written to a file, they are written 
sequentially, and assigned an index that is their location 
in the file. They may be retrieved randomly by using this 
index value. 

The p-System name for files of figures always contains 
the suffix .FOTO. It is not necessary to use this suffix 

when calling Read_figure_file or Write_figure_file (if 

absent, it is supplied automatically). 

Function Read_figure_file 

(title: string): integer; 

Specifies the title of a file from which all subsequent fig¬ 
ures are loaded. If a figure file is already open for reading 
when this function is called, it is closed before the new file 
is opened. Only one figure file may be open for reading at 
a single time. This function returns an integer value 
which is the ioresult of opening the file. 

Function Write_figure_file 

(title: string): integer; 
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Creates an output file into which user-created figures 
may be stored. If another figure file is open for writing 
when this function is called, it is closed, with lock, before 
the new file is created. Only one figure file may be open 
for writing at a single time. This function returns an inte¬ 
ger result which is the ioresult of the file creation. 

Function Load_figure 

(index: integer): integer; 

Loads the indexed figure from the current input figure 
file and assigns it a new, unique, figure number. An auto¬ 
matic Create_figure is performed. If the operation fails 

for any reason, a Figure_number of zero (0) is returned. 

Function Store_figure 

(figure: integer): integer; 

Sequentially writes the designated figure to the output 
figure file. The function returns an integer that is the 
figure’s positional index in the current output figure file. 
Positional indexes start at one (1). If the index returned 
equals zero (0), Turtlegraphics did not successfully store 
the figure. 

Routine Parameters 

The next example shows the interface section for the Tur¬ 
tlegraphics unit, including the parameters to all Turtle- 
graphics routines: 


unit Turtlegraphics; 
interface 

procedure Display_scale! min_x, min_y, 

max_x, max_y: real ); 

function Aspect _ ratio : real ; 

function Create _ figure! x _ size, y _ size: 

real) : integer ; 

procedure Delete_figure! screen: 

integer ); 

procedureViewport! min _ x, min_ y, max_x, 

max _ y : real ); 
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procedure FiUscreen( screen: 

integer ; shade: 
integer ); 

procedure Background (screen: integer ; 

shade : integer ); 

function Read _ pixel! screen: integer ; 
x, y : real ) : integer ; 

procedure Set_pixel! screen:integer ; 

x,y: real ; shade:color); 

procedure Get _ Figure! source _ screen: 

integer , 

corner _ x, corner _ y: real ; 

mode : integer ); 

procedure Put_Figure( destination_screen: 
integer , 

corner _ x, corner _ y: real ; 

mode : integer ); 

function Read_figure_file( title: string ): 

integer ; 

function Write__figure._file( title : string): 
integer ; 

function Load^figure! index : integer ): 
integer ; 

function Store figure! figure: integer ): 
integer ; 

procedure Activate _ Turtle! screen: 

integer ); 

function Turtle _ x : real ; 

function Turtle _ y : real ; 

function Turtle_angle : real ; 

procedure Move! distance : real ); 
procedure Moveto! x,y : real ); 
procedure Turn! rotation : real ); 
procedure Turnto! heading : real ); 

procedure Pen_mode! mode : integer ); 

procedure Pen _ color! shade : integer ); 

procedure WChar! c: char ; copymode, shade: integer ); 
procedure WString! s: string ; copymode, shade: integer ); 


Sample Program 

Here is a sample program that illustrates a number of 
Turtlegraphics routines: 


program Spiraldemo; 

uses Turtlegraphics; 

const nop = 0; 
substitute = 1; 
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var I, J, Mode: integer : 

C: char ; 

Color: integer ; 

Seed: integer ; 

LX, LY, UX, UY: real; 

function Random (Range: integer ): integer ; 
begin 

Seed: = Seed * 233 -h 113; 

Random: = Seed mod Range: 

Seed:= Seed mod 256; 

end ; 

procedure ClearBottom; 

{clears bottom line of screen 
for prompts} 
begin 

Penmode (nop); 

Moveto (0, 0); 

WString (' \ substitute, 1); 

end ; 
begin 

ClearBottom; {various initializations} 

WString ('ENTER RANDOM NUMBER: ', substitute, 1); 
read (keyboard , Seed); 

ClearBottom; 

Display Scale (0, 0, 200*Aspect Ratio, 200); 

{Aspect Ratio used so 
pattern will be round} 

Color: = 0; 

WString ('ENTER VIEWPORT LL CORNER: ', substitute, 1); 
read (keyboard , LX,LY>; 

ClearBottom; 

WString ('ENTER VIEWPORT UR CORNER:', substitute, 1); 
read ( keyboard , UX.UY); 

ClearBottom; 

WString ('PENMODE = ', substitute, 1); 
read ( keyboard , MODE); 

ViewPort (LX, LY, UX, UY); {create port} 

PenMode (0); 

{use blank pen while moving it} 

Moveto (100* Aspect_Ratio, 100); 

{put turtle in center of port} 

{Aspect_Ratio ensures that it will be 

correctly centered} 

PenMode (Mode); 

{set pen to selected color} 

J:= Random(90)-i-90; 

{angle by which turtle will move 
note that turtle begins facing right 
and will move counterclockwise 
(J is positive)} 













for I:= 2 to 200 do 

{draw spiral in 200 segments 
of increasing length} 
begin 

{cycle through the colors} 

Color: = Color+1; 
if Color > 3 then Color: = 1; 
PenColor (Color): 

Move(I); 

Turn(J); 
end ; 

I:= Create_Figure (UX-LX, UY-LY); 

{create figure the size of the port} 
PutFigure (I, LX, LY, 1); 

(save it: mode overwrites 
old figure (if any)} 

ViewPort (0, 0, Aspect Jiatio*200, 200); 
{respecify viewport in 
the lower left corner} 

GetFigure (I, 0, 0, 1); 

{display finished spiral} 
readln ; 

{clear user input buffer} 
end . 
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INTRODUCTION 


Your Pascal programs on the Texas Instruments Professional 
Computer can use the file management units to accomplish sev¬ 
eral tasks usually performed by the filer. There are four file man¬ 
agement units: 

DIR.INFO.CODE 
WILD.CODE 
SYS. INFO.CODE 
FILE.INFO.CODE 

DIR.INFO provides directory information. Your programs may 
use this unit to: 

• List directories. 

• Parse file names into volume ID, file name, file type, and 
size specification. 

• Change file names. 

• Change the date associated with a file or volume. 

• Remove files. 

• Krunch a volume. 

• Mount and dismount subsidiary volumes. 

• Grant exclusive access rights to a directory by task. 

• Release those exclusive access rights. 
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WILD provides wild card string matching facilities. 

FILE.INFO allows your programs to: 

• Determine if files are opened. 

• Find the length of a file. 

• Determine what storage volume contains a given file. 

• Extract the file title with its suffix, from a file. 

• Find the starting block of a file. 

• Determine whether or not a volume is a storage volume or a 
communications volume. 

• Return the date associated with a file. 

SYS.INFO allows your programs to: 

• Determine the device number or volume name of the system 
disk (the volume referred to by an asterisk, (*)). 

• Determine the file names for the work files and the volumes 
on which they reside. 


INTERFACE SECTIONS 


In order to take advantage of the file management units, your 
Pascal programs should use them in a USES declaration. (These 
units are not available to FORTRAN and BASIC programs.) For 
example, to have access to all four units, you would use this decla¬ 
ration: 


USES {$U wild.code} WILD, 

{$U dir.info.code} DIR INFO, 
{$U sys.info.code} SYS_INFO, 
|$U file.info.code} FILE _ INFO; 
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You can then call the routines these units contain from your pro¬ 
grams. Here are the interface sections of the four file manage¬ 
ment units with embedded comments. The routines are described 
in detail throughout the rest of this chapter. 

Unit Interface 

Unit Wild; 

Interface 

Type 

D_PatRecP = D _ PatRec; 

I) PatRec = Record 

CompPos, { starting position of pattern in subject string } 

CompLen, { length of pattern in subject string } 

WildPos, { starting position of pattern in wild string } 

WildLen : Integer; { length of pattern in wildcard string } 

Next: D_PatRecP; { next pattern } 

End; { D_PatRec} 

Function D_Wild _ Match(Wild, Comp : String; Var PPtr : D_ PatRecP; 

PInfo : Boolean): Boolean; 

{ Compares two strings (one containing wildcards) and returns true if they match. Includes 
information about pattern matching that occurred if re quested (by PInfo)} 
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Unit Interface 


Unit Dir _ Info; 

Interface ^ 

uses 

(*$U WILD.CODE*)wild: 

Type 

D_DateRec = Packed Record 
Month: 0..12; 

Day: 0..31; 

Year: 0..100; 

End; 

D_NameType = (D_Vol, D Code, D_Text, I) Data, D_SVol, D Temp, D — Free); 

D_ Choice = Set of D NameType; 

D ListP = D_List; 

D _ List = Record 

D .Unit: Integer; { Unit # of entry } 

D ^Volume: String[7]; { volume name of unit } 

D _VPat : D PatRecP; { volume pattern info } 

D_NextEntry : D _ListP; { Next entry in list } 

Case D _ IsBlkd : Boolean Of 

True : (D Start, { Starting block of entry} " s 

Length : Integer; { Length (in blocks) of entry } 

Case I) Kind : D NameType Of 

D _Vol, { Everything but D_Free } 

D. _Temp, 

D_Code, 

D Text, 

I) Data, 

D_SVol : (D_ Title : String[15);{ File name } 

D_ FPat : I) PatRecP; { name pattern info} 

D_ Date : D_DateRec; { File date } 

Case D NameType of { H of files on vol} 

D Vol; (D _ NumFiles : Integer))); 

End; 


D_Result = (D _Okay, { Mission accomplished } 

D _ Not _ Found, { Couldn’t find name and/or type } 

D_Exists, { Name already exists; no name change made } 
D Name Error. { Illegal string passed } 

D_Off_Line, { Volume not on line } 

D Other); { Miscellaneous error } 
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Function D__Dir ListlD_Name : String; D__ Select : I) _ Choice; 

Var D._ Ptr : D_ListP; D _ PInfo : Boolean) : D_ Result; 

{ Creates pointer to list of names of specified NameTvpes 

(D_ Select), matching specified I)_Name (wildcard characters allowed). Includes 

information about pattern matching that occurred if requested (by D PInfo) } 

Function D Scan _ Title(D _Name : String; Var I) .Volume, D Title : String; 

Var I)_Type : D__NameTvpe; Var D Segs ; Integer) ; D Result; 

{ Parses D_Name } 

Function I) Change _ Named) OldName, D._ NewName : String; D RemOld : Boolean) 

; D_ Result; 

{ Changes file name in I) OldName to name in D_NewName, removing already existing 

files of name in D _ NewName if D RemOld is set } 

Function D Change Dated)_Name : String; D_ NewDate : I) DateRec; D_ Select : 

D Choice) : D_Result; 

{ Changes date of directory or file name in D Name to date specified by D_NewDate. 

D_Name may contain wildcards } 

Function D_Rem_Files (D_Name : String; I) Select : D__Choice) : D_Result; 

{ Removes file of specified name (wildcards allowed) } 

Procedure D_Lock; 

Procedure I) .Release; 

{ Provide means to limit use of Dir Info routines to one task at a time in multi-tasking 
environments } 

Function D_Krunch (D__Unit, 

I)_Block : Integer) : D _ Result; 

{ Collects all unused space on a volume around I) .Block. This unit must not be in use 
when this operation is performed. } 

Function D _ Mount (D_File_Name : String) : D Result; 

Function D_DisMount (D VoL_Name : String) : D Result; 

{ Provides a means of mounting and dismounting subsidiary volumes. Wild cards may be 
used. } 




Unit Interface 

Unit Sys_Info; 

Interface 

Type SI__Date Rec = Packed Record 
Month : 0..12; 

Day :0..31; 

Year : 0..99; 

End; { SI_Date_Rec } 

Procedure SI Code^Vid (Var SI Vol: String); 

{ Returns name of volume containing current workfile code } 

Procedure SI Code_Tid (Var SI _Title : String); 

{ Returns title of current workfile code } 

Procedure SI _ Text _ Vid (Var SI_Vol : String); 

{ Returns name of volume containing current workfile text} 

Procedure SI_ Text_Tid (Var SI Title : String); 

{ Returns title of current workfile text} 

Function SI_Sys _ Unit : Integer; 

{ Returns number of bootload unit } 

Procedure SI Get Sys Vol (Var SI Vol : String); 

{ Returns system volume name } 

Procedure SI _ Get Pref Vol (Var SI _ Vol : String); 

{ Returns prefix volume name } 

Procedure SI Set Pref Vol (SI Vol: String); 

{ Sets prefix volume name } 

Procedure SI _ Get_Date (Var SI _ Date : SI_Date Rec); 

{ Returns current system date } 

Procedure SI. Set_Date (Var SI_Date : SI_Date_Rec); 

{ Sets current system date } 
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Unit Interface 

Unit File _ Info; 

Interface 

Type F File_ Type = file; 

F_Date Rec = Packed Record 
Month: 0..12; 

Day: 0..31; 

Year: 0..100; 

End; { F _ Date__Rec } 

Function F Open (var fid; F File Type):boolean; 

(* returns true if the file is open and false if not open *) 

Function F_Length (Var Fid: F _File_Type): Integer; 

{Returns the length of the file attached to the Fid identifier. 
If the file is not opened result is returned as zero} 

Function F. _Unit_number (Var Fid: F _File_ Type): integer; 

{Returns the unit containing the file attached to the Fid 
identifier. If there is no file opened to Fid, the function 
result is Zero.} 

Procedure F_ Volume (Var Fid: F File_Type; 

Var File_Volume : String); 

{Returns the name of the volume containing the file attached 
to the Fid identifier. If there is no file opened to Fid, 
the file_volume is set to a null string.} 

Procedure F _ File_Title (Var Fid: F _ File Type; 

(Var File_Title: String); 

{Returns the title (with suffix) of the file attached to the 
Fid identifier. If there is no file opened to Fid, 
the File title is set to the null string.} 

Function F_Start (Var Fid: F _ File Type): integer; 

{Returns the block number of the first block of the file 
attached to the Fid identifier. If there is no file opened 
to Fid, the function result is returned is zero.} 




Function F _ is _ Blocked (Var Fid: F_File Type): Boolean: 


{Returns a boolean that is TRUE if the file attached to the Fid identifier is located on a 
block-structured unit. If there is no file opened for the Fid or if the device is not block 
structured, the function result is set to false.} 


Procedure F Date (Var Fid: F File Type; 

Var File_Date: F Dat» 


Rec); 


{Returns a record indicating the last access date for the file 
attached to the Fid identifier. If there is no file opened to 
Fid, the F'ile Date is unchanged.} 


DIRECTORY INFORMATION 

This section describes the directory information unit, called 

DIR_INFO, which enables your programs to access file system 

information. 

Many of your applications may need to access and modify direc¬ 
tory information. This unit makes it easy to perform most of 
these sorts of operations. There are other ways to do this. The 
most common solution is to construct your own routines that 
directly access the operating system’s data structures. However, 
the interfaces provided by this unit make directory information 
access much safer and easier. 
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The DIR_INFO unit provides the following capabilities to your 

programs: 

• Directory Information Access. For any on-line storage vol¬ 
ume, DIR_INFO returns the volume name, volume date, 

number of disk files on volume, amount of unused space, 
and attributes of individual disk files. 

• Directory Manipulation. DIR_INFO provides routines for 

changing the date or name of a disk file or volume, removing 
files from a volume, and mounting and dismounting subsid¬ 
iary volumes. 

• File Manipulation. DIR_INFO allows you to Krunch a vol¬ 

ume in a similar fashion to the Filer. 

• Wild Cards. DIR_INFO uses the UNIT WILD, which pro¬ 
vides a wild card convention for pattern matching of string 

variables. Most DIR_INFO routines recognize the wild 

card convention in their file name arguments. 

• Error Handling. DIR_INFO defines a standard error result 

(similar to UCSD p-System I/O results) for routines 
involved with file names and directory searches. 

• Multi-tasking Support. DIR_INFO provides routines for 

protecting file system information from contention between 
concurrent tasks. These routines ensure that only one task 
can modify file system information at a time. 

Notation and Terminology 

In this chapter, a variant of Extended Backus-Naur Form 
(EBNF) is used as a notation for describing the form of 
wild cards and file names. Meta-words are words that 
represent a class of words; they are shown in the text by 
the use of angle brackets < \ >. The following expression 
is an example: 

< fish> = trout | salmon | tuna 
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The equal sign indicates that the meta-word on the left 
side can be substituted with the word on the right side. 
The bar (|) separates possible choices for substitution. In 
this example, fish can be replaced by trout , salmon, or 
tuna. 


An item enclosed in square brackets [\ ] may be substi¬ 
tuted into a textual expression. For example, 
[micro]computer can represent the text strings computer 
and microcomputer. 


An item enclosed in braces {\ } can be substituted zero or 
more times into a textual expression. The following 
expression represents responses to jokes possessing 
varying degrees of humor. 

< joke-response> = {ha} 


Literal occurrences of characters or strings of characters 
are delimited by quotes to avoid confusing them with 
notational definitions. For example: 



left-bracket = “< ” / “{” / “[” 


The term < file-object> is used throughout this chapter; 
it is a generic term encompassing communications and 
storage volumes, files, and unused areas on storage 
volumes. 


File Name Arguments 


Most DIR_INFO routines accept file name arguments. 

The file name specifies the volume and/or file to be 
accessed by the routine. You should see the UCSD p-Sys¬ 
tem Operating System Reference Manual , TI Part Num¬ 
ber 2232395-0001, for a complete description of UCSD p- 
System files and file names if you are not familiar with 
them. 
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Volume names and file names can contain wild cards 
(which are described in the next section). Device numbers 
and colons separating volume IDs and file names must 
appear literally; they must be independent of any wild 
card. 

All DIR_INFO routines except D_Scan_Title ignore 

file length specification. In some cases, file name conven¬ 
tions in DIR_INFO differ slightly from UCSD p-System 

file name conventions: 

• DIR_INFO considers an empty volume ID/file 

name argument to specify the prefix volume; that is, 
< file name> is empty (implying a volume refer¬ 
ence), and <volume-ID> is empty (implying the 
prefixed volume). An empty string is not a valid file 
name in the p-System. 

• DIR_INFO interprets wild card file names of the 

form <vol-name>:= to be valid volume specifiers. 

This is consistent with DIR_INFO’s definition of 

the ( = ) wild card, but inconsistent with the UCSD 
p-System filer's interpretation of the ( — ) wild card. 
The filer does not accept file names of this form as 
volume specifiers. 

File Type Selection 

Some DIR_INFO routines accept a < file-type> parame¬ 
ter (named D_SELECT) which is used to specify the file 

objects to be accessed. (File objects include volumes, 
unused areas on storage volumes, temporary files, text 
files, code files, and other types of files.) The file type 
parameter is necessary because file names alone cannot 
completely specify all types of file objects (such as 
unused disk areas). The routines that generate directory 
information use both the file name argument and the 

D_SELECT parameter to determine the file objects on 

which to return information. 
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DIR_INFO defines a scalar type, which is used to spec¬ 
ify file objects. D_SELECT is declared as a set of this 

type; a file object is selected by including its correspond¬ 
ing scalar in D_SELECT. 

File object types: 

D_NameType = (D_Vol, D_Code, D_Text, 

D_Data, D_SVol, D_Temp, 

D_Free); 


D_Choice = Set Of D_NameType; 

Here is a description of these scalar values: 


• D_Vol—Selects all volumes matching the file name 

argument. Note that while volume names can con¬ 
tain wild cards, device numbers must be specified 
literally. 

• D_Free—Selects all unused areas of disk space on 

the volumes matching the file name argument. 


D_Temp—Selects all temporary files matching the 

file name argument. Files are considered temporary 
if they have been opened—and not yet closed—by a 
program. 


• D_Text—Selects all text files matching the file 

name argument. 

• D_Code—Selects all code files matching the file 

name argument. 


D_Data—Selects all data files matching the file 

name argument. 

D_SVol—Selects all svol files matching the file 

name argument. 
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File Dates 


Disk files and disk volumes are assigned < file-dates>. 

File dates are stored in records of type D_Date_Rec. 

They are accessed and modified by the DIR_INFO 

routines D_Dir_List and D_Change_Date. 

D_Date_Rec is declared as follows: 

D_DateRec = Packed Record 

Month: 0..12; 

Day: 0..31; 

Year: 0..100; 

End;{ D_DateRec } 

A year value of 100 in a file date record indicates that the 
object is a temporary disk file. (This is a UCSD p-System 
file system convention.) 

Error Results 

All DIR_INFO routines that access file system informa¬ 

tion return a value reflecting the result of the file system 
operation. This result indicates either that the routine fin¬ 
ished without errors or that an error occurred. Valid infor¬ 
mation is not returned when routines return a result 
value indicating that an error has occurred. 

The following items describe conditions that can cause 
errors: 

• The specified files, volumes, or unused spaces can¬ 
not be found in the disk directory. 

• The specified unit is off-line. 

• The file name argument has improper syntax. 

• The specified file name conflicts with an existing 

file. 
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An error never causes a function to terminate abnor¬ 
mally. Errors that the routine cannot identify explicitly 
are flagged. This is done by returning a result that indi¬ 
cates an unknown error has occurred. 

DIR_INFO defines the following scalar type to describe 

the possible errors encountered: 

Type D _ Result = (D _ Okay, 

D_Not_Found, 

D_Exists, 

D_Name_Error, 

D_Off_Line, 

D _ Other); 

You should refer to the descriptions of the various 
routines for details concerning the results of errors and 
the status of directory information returned during error 
conditions. 

The DIR_INFO Routines 

Function D_Krunch 

(D_Unit:integer; D_Blockrinteger): 

D_Result; 


This function Krunches the files on the volume specified 

by D_Unit. This is similar to the filer’s K(runch activity. 

The block indicated by D_Block is the point around 

which the unused disk space is consolidated. Files located 
before D_Block are moved forward (toward the direc¬ 

tory) and files after it are moved backward (toward the 
last track). 
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CAUTION 


Using D_Krunch on a volume that contains 

an executing or open file (including the operat¬ 
ing system) may destroy the files. If function 

D_Krunch changes the location of an open or 

executing file, the system returns data to the 
previous—not the present—location of the file. 

Function D_Mount 

(D_File_N ame: String): D_Result; 

The D_File_Name parameter identifies an svol file. The 

corresponding subsidiary volume is mounted unless 
D_Result indicates otherwise. Wild cards may be used. 

Function D_DisMount 

(D_Vol_Name:String):D_Result; 

The subsidiary volume identified by the D_Vol_Name 

parameter is dismounted. This volume must be a subsid¬ 
iary volume. 

Function D_Scan_Title 

(D_NAME:String; Var D_VOLUME, 

D_TITLE: String; Var D_TYPE: 

D_NameType; Var D_SEGS: 

Integer): D_Result; 

D_Scan__Title parses the UCSD p-System file name 

passed in D_NAME and returns the file name's volume 

ID, file name, file type, and file length specifier. The func¬ 
tion result indicates the validity of the file name argu¬ 
ment. D_Scan Title does not determine whether or not 

D_Name actually exists. 

D_Scan_Title accepts the following parameters. 
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• D_NAME—A string containing a UCSD p-System 

file name. 

• D_VOLUME—A string that returns the volume 

ID contained in D_NAME. If D_NAME contains 

no volume ID or if the volume ID is ( : ), 
D_VOLUME is assigned the system’s default vol¬ 

ume name. If the volume ID is ( * ) or ( *: ), 

D_VOLUME is assigned the system’s boot volume 

name. Volume names assigned to D_VOLUME 

contain only uppercase characters and do not con¬ 
tain blank characters. 

• D_TITLE—A string that returns the file name 

contained in D_NAME. If D_NAME does not 

contain a file name, D_TITLE is assigned the 

empty string. File titles assigned to D_TITLE con¬ 

tain only uppercase characters and do not contain 
blank characters. 

• D_TYPE—A scalar which returns a value indicat¬ 

ing the file type of the file name contained in 
D_NAME. 

The following items define D_TYPE’s scalar type: 

• D_NameType = (D_Vol, D_Code, D Text, 

D_SVol, D_Data, D_Temp, D_Free,); 

• D_TYPE is set to D_Vol if the file name in 

D_NAME is empty. D_TYPE is set to D_Code if 

the file name is terminated by .CODE or to D_Text 

if the file name is terminated by .TEXT or .BACK. 

D_TYPE is set to D_SVOL if the file name ends 

with .SVOL (a subsidiary volume). If none of the 

above holds true, D_TYPE is set to D_Data. 

Only the suffix of a file is used to determine 
what type it is. For example, the file name 
SYSTEM.COMPILER is returned as a data file 
because its suffix is not .CODE. 
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D_SEGS—An integer that is assigned a value indicating 

the presence of a file length specifier in D_NAME. The 

value returned in D_SEGS is assigned as follows: 


LENGTH SPECIFIER 


D_SEGS VALUE 


[< number> ] 


< number> 


[*] 

< not present> 


-1 

0 


D_Scan_Title returns a function result of type 

D_Result. The only scalar values returned by 

D_Scan_Title are D_Okay and D_Name_Error; they 

have the following meanings: 

• D_Okay—No Error. All information returned by 

D_Scan_Title is valid. 

• D_Name_Error—Illegal file name syntax in 

D_NAME. The information returned by 

D_Scan_Title is invalid. 

Example Program 

Program Scan Test; 

Uses 

|*$U WILD.CODE*) 
wild, 

(*$UDIR. INFO.CODE*) 

Dir Info; 

Var 

Name, 

Volume, 

Title : String ; 

Typ : D_NameType; 

Seg Flag : Integer ; 

Result : D Result; 

Ch : Char ; 

Begin { Scan Test } 

Writeln ('— D ScanTitle Test'); 
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Repeat 
Writeln ; 

Write ('File name to parse: '); 

Readln (Name); 

Result := D ScanTitle(Name, Volume, Title, 

Typ, Seg—Flag); 

Writeln ('parsed: '); 
case result of 
d okay:begin 

Writeln (' Volume name — ', Volume); 

Writeln (' File name — \ Title); 

Write (' File type — '); 

Case Typ Of 

D._ Text: Writeln ('text file'); 

D_ Code : Writeln ('code file'); 

D_Data : Writeln ('data file'); 

D_SVol: Writeln ('svol file'); 

End; { Cases } 

If Seg Flag < > 0 Then 
Writeln (' Segment flag — Seg Hag); 
end; 

d_name error:writeln (' Name error'); 
end; 

Writeln ; 

Write ('Continue? '); 

Read (Ch); 

Writeln; 

Until Chln['n'. 'N']; 

End. { Scan_Test } 

Function D_Dir_List 

(D_NAMErString; D_SELECT : D_Choice; 

Var D_PTR : D_ListP; 

D_PINFO : Boolean): D_Result; 




















D_Dir_List creates a list of records containing direc¬ 

tory information on volumes and disk files. This informa¬ 
tion includes volume names and device numbers of 
storage and communications on-line volumes, numbers of 
files on storage volumes, lengths and starting blocks of 
disk files and unused disk spaces, file names and types, 
and file dates. The function result value indicates invalid 
file name arguments, off-line volumes, or not-found files. 

D_Dir_List optionally provides information describing 

how the wild card file name argument matched files 
and/or volumes. 

D_Dir_List accepts a set specifying the file types on 

which to return information and a string containing a file 

name. D_Dir_List returns a pointer to a linked list of 

directory information records. Each record contains the 
name of a file or volume which matches the file name 
argument and also is one of the types specified in the file 
type set. 

• D_NAME—The D_NAME parameter contains a 

file name which can contain wild cards. 

• D_SELECT—The D_SELECT parameter is a set 

specifying the directory objects for which informa¬ 
tion is to be returned by D_Dir_List. See the file 

type selection for more information on directory 
object selection. 

• D_PTR—The D_PTR parameter is assigned a 

pointer to a linked list of records containing direc¬ 
tory information for all specified file objects. To be 
listed in a directory, a file object must meet the fol¬ 
lowing criteria: 

— It must reside on a volume which matches the 
volume ID in D_NAME. 

—If the object is a disk file, it must match the file 
ID in D_NAME. 
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—It must belong to one of the types included in 
D_SELECT. 

The linked list contains one record for each file object 
matched. The records are defined as follows: 

D_List? = D_List; 

I)_List = Record 

D_Unit: Integer ; 

I) Volume : String [7]; 

I) VPat: D PatRecP; 

D NextEntry: I) ListP; 

Case I) IsBlkd : Boolean Of 
True : (D Start, 

I) Length : Integer ; 

Case D Kind : D . NameType Of 

D _ Voh 

D Temp, 

D. _ Code, 

I) Text, 

D Data, 

D JSVol: 

(D_Title: String (15); 

D FPat: D PatRecP; 

I) Date: I) DateRec; 

Case D _ NameType of 

D Vol:(D NumFiles: Integer ))); 

End; 


The D_List record fields return the following informa¬ 
tion for each file object in the D_Ptr list. 

• D_Unit returns the device number of the device 

containing the object. 

• D_Volume returns the name of the volume contain¬ 

ing the object. 
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• D_VPat is a pointer to pattern matching informa¬ 

tion collected while comparing volumes to the vol¬ 
ume ID in D_NAME (see the section on the wild 

unit for details on pattern matching information). 
D_VPat is set to NIL if pattern matching informa¬ 

tion is not requested. 

• D_NextEntry is a pointer to the next directory 

information record in the list. It is set to NIL if the 
current record is the last record in the list. 

• D_IsBlkd is set to true if the file object is (or 

resides on) a storage volume. Records describing 

serial volumes have D_IsBlked set to false; the 

remaining fields are undefined. 

The following fields exist only in records describing file 

objects stored on storage volumes (that is, D_IsBlkd is 

TRUE): 

• D_Start contains the starting block number of the 

file object. If the object is of type D_Vol, this value 

is interpreted as the block number of the first block 
on the volume (that is, 0 for disk volume). 

• D_Length contains the length (in blocks) of the file 

object. If the object is of type D_Vol, this value is 
interpreted as the total number of blocks on the vol¬ 
ume (such as 320 for a typical single density, Sc¬ 
inch diskette.) 

• D_Kind indicates the type of the file object 

described by the current record. 
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The following fields exist only in records describing disk 
file objects other than unused disk areas (such as 

D_Kind in [D_Vol, D_Temp, D_Code, D_Text, 

D_Data, D_SVol]): 

• D_Title contains the file name of the object. For 

objects of type D_Vol, this field contains the empty 

string. 

• D_FPat is a pointer to pattern matching informa¬ 

tion collected while comparing file names to the file 

ID in D_NAME (see wild card UNIT for details on 

pattern matching information). D_FPat is set NIL 

if pattern matching information is not requested or 
if the file ID in D_NAME is empty. 

• D_Date contains the file date for the current 

object. 

• D_NumFiles is valid only for objects of type 

D_Vol; it contains the number of files in the vol¬ 

ume’s directory. 


NOTE 

An .SVol file (which contains a subsidiary vol¬ 
ume) appears as any other file on the principal 

volume. This means that D_NumFiles does 

not correspond to an .SVol file. However, when 
accessed by its volume ID, the actual subsid¬ 
iary volume returns with a valid D_NumFiles 

entry. 

File information is returned (in a linked list accessed by 
D_Ptr) in the following order: 


1. Volume on highest numbered device that matches 
D_NAME (if D_Vol is in D_SELECT) 




2. Files in directory of this volume that match 

D_NAME and are of one of the types in 

D_SELECT (if a file type is in D_SELECT) 

Last file on volume 


First file on volume 

3. Unused spaces on this volume (if D_Free is in 

D_SELECT) 

Last free space on volume 


First free space on volume 

4. Volume on lowest numbered device that matches 

D_NAME (if D_Vol is in D_SELECT) 

5. Files in directory of this volume that match 

D_NAME and are of one of the types in 

D_SELECT (if a file type is in D_SELECT) 

Last file on volume 


First file on volume 

6. Unused spaces on this volume (if D_Free is in 

D_SELECT) 

Last free space on volume 


First free space on volume 
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D_PINFO 


When set to TRUE, the D_PINFO parameter indicates 

that pattern matching information should be returned 

in a linked list accessed by D_PTR. The 

D_WILD_MATCH function collects this information 

while comparing volume and file IDs; it is useful for 
determining how the wild cards were expanded in 

D_NAME. Information is returned in two pointers; one 

for volume names matched (named D_VPat) and one for 

file IDs matched (named D_FPat). 

The following is an example of pattern record lists: 

D_NAME is set to '=:TEST{l-9} = ' 

Two volumes contain files which match D_NAME: 

BOOT contains TEST5.CODE 
WORK contains TEST5.TEXT 

For BOOT:TEST5.CODE, D_Volume is BOOT, 

D_Title is TEST5.CODE, and D_VPat returns a 

pointer to the following information. 

1. WildPos is 1, WildLen is 1 
CompPos is 1, CompLen is 4 
('='matches 'BOOT') 

D_FPat returns a pointer to the following information. 

1. WildPos is 1, WildLen is 4 
CompPos is 1, CompLen is 4 
('TEST' matches 'TEST') 

2. WildPos is 5, WildLen is 5 
CompPos is 5, CompLen is 1 
('{1-9}' matches '5') 




3. WildPos is 10, WildLen is 1 
CompPos is 6, CompPos is 5 
('='matches '.CODE') 

A similar list is returned for WORK:TEST5.TEXT. 

NOTE 

If the volume ID in D_NAME consists of a 

device number (such as #5), the volume 
assigned to the device is defined to match the 

volume ID in D_NAME. The Pos and Len 

pointers are set as in the following example. 

D_NAME is set to “#5:” 


A disk volume named MYDISK resides in device 5. 

1. WildPos is 1, WildLen is 2 
CompPos is 1, CompPos is 4 
('#5' matches 'MYDISK') 

NOTE 

D_FPat and D_VPat never contain invalid 

information. If information is unavailable or 
has not been requested, the pointers are set to 
NIL. 
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Function Result 


D Dir List returns a value of type D Result. 

D Dir List can return all scalar values defined in 

D_Result except D_Exists; the values have the follow¬ 

ing meanings: 

• D_Okay—No error. All D_Ptr information is 

valid. 

• D_Not_Found—No such file/volume found. No 

match found for D_NAME. D_Dir_List sets 

D_Ptr to NIL. 

• D_Name_Error—Illegal syntax in D_NAME. 

D_Dir_List sets D_Ptr to NIL. 

• D_OffLine—Volume off-line. The volume specified 

by D_NAME was not on-line. This error occurs 

only when the volume ID in D_NAME does not 

contain wild cards (that is, a single volume is speci¬ 
fied, and it is off-line). If the volume name in 

D_NAME contains wild cards but does not match 

any on-line volumes, D_Dir_List returns 

D_Not_Found. D_Ptr is set to NIL. 

• D_Other—Unknown error. D_Dir encountered an 

error it could not identify, but which interrupted 

normal execution of the function. D_Ptr is set to 

NIL. 

Example Program 

The following program is a general purpose directory 
lister; it accepts a string containing wild cards and 
creates a list of matching files and (if requested) pattern 
matching information for the files. Note that the program 
uses the MARK and RELEASE intrinsics to remove the 
D_Dir_List information from the heap after the infor¬ 

mation has been used. 
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Program Listtest; 

Uses 

(*$U WILD.CODE*) 
wild, 

(*$UDIR. INFO.CODE*) 

Dimfo; 

Var 

Select: D_Choice; 

Want_Patterns : Boolean ; 

Heap_Ptr: Integer ; 

Segs: Integer ; 

Typ : D_NameType; 

Volume, Title, Match : String ; 

Result: D _ Result; 

Ch: Char ; 

Ptr : D _ ListP; 

Procedure GiveChoice(Choice: String ; 

Kind : D _ Choice); 

Var 

Ch: Char ; 

Begin 

Write (' ',Choice,' ?'); 

Read (Ch); Writeln ; 

Ch In ['y', 'Y'l Then Select := Select + Kind; 

End; { GiveChoice } 

Procedure Print Patterns! PatPtr : D_PatRecP; 

Comp, Wild : String ); 

Var 

Count: Integer ; 

Begin { Print Patterns } 

Count := 1; 

Writeln (Type < cr> for patterns'); 

Readln ; Writeln ; 

Repeat 

Writeln ('Pattern ', Count,':'); 

with PatPtr Do 

Begin 

Writeln (' Comp : ', Comp); 

If CompLen <> 0 Then 
Write ( ,A ':(CompPos + 9)); 

If CompLen > 1 Then Write ( ,A ':(CompLen -- 1)); 
Writeln ; 

Writeln (' Wild : ', Wild); 

Write ( ,A ':(WildPos 4- 9)); 

If WildLen > 1 Then Write ( /A ':(WildLen -- 1)); 
Writeln ; Writeln ; 

End; 

PatPtr := Pat Ptr A . Next; 

Count ;= Count 4 1; 

Until PatPtr = Nil 
End; { Prints Patterns } 

























Procedure Print Info(Ptr : D ListP); 


Begin { Print_Info } 

Repeat 
with Ptr Do 
Begin 

If D_IsBlkd Then 

Case D Kind Of 

D _ Free : Write ('Free space on '); 

D _Vol: Write ('Volume '); 

D Temp : Write ('Temporary file on 
D^Text: Write ('Text file on 
D Code : Write ('Code file on '); 

D Data : Write ( Data file on '); 

D „SVol: Write ('SYol file on 
End{ Cases } 

Else 

Write ('Communications volume '); 

Writeln(D Volume); 

If Want Patterns And (D VPat < > Nil) Then 
Begin 

Writeln ; 

Writeln ( ' Volume patterns:'); 
Print__Patterns(D VPat, D Volume, Volume); 
End; 

Writeln (' Unit number.'. D _Unit); 

If I) _IsBlkd Then 
Begin 

If Not (D Kind In [D Vol, D Free]) Then 

Writeln (' File name.', D Title); 

If D. Kind < > D Free Then 
Begin 

If Want Patterns And (D FPat < > Nil) Then 
Begin 

Writeln (' File name patterns:'); 

Print Patterns(D FPat, D Title, Title); 
End; 

With D_Date Do 

Writeln (' File date . 

Month, 7\ Day,'/', Year); 

End; { IfD Kind} 

If D Kind = D Vol Then 
Writeln (' Files on volume... ', D NumFiles); 
Writeln (' Starting block D Start); 

Writeln (' File length. ', D_ Length); 

End; { If D IsBlkd} 

End; { With Ptr A } 

Writeln ; 

Write ('Type <cr> for rest of list'); 

Readln ; Writeln ; 

Ptr := Ptr A .D NextEntry; 

Until Ptr = Nil 
p]nd; { Print Info } 
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Begin { D Test } 

Repeat 

Mark (Heap _ Ptr); 

Select := I); 

Writeln ('Directory Lister — '); 

Write ('Volume and or file name to match: 

Readln (Match); 

Write ('Return pattern matching information? [y n]'); 

Read (Ch): Writeln; 

Want _ Patterns := Ch In ['y', 'Y'); 

If Want_Patterns Then 

Result := D ScanTitle(Match, Volume, Title, Typ, Segs); 
Writeln ('Types [ yin ]: '); 

GiveChoice('Directories', (D Vol]); 

GiveChoice('Text Files ', [D._Textj); 

GiveChoice('Code Files ', [D _ Code]): 

GiveChoice('Data Files ', [D Data]); 

GiveChoice('Temp Files ', [D Temp]); 

GiveChoice('Free Space ', ]D .Free]); 

GiveChoice('SVol Files ', ]I)_SVol]); 

Result := D _ Dir Lis t( Match, Select. Ptr. Want_ Patterns); 

Writeln; 

If PtrO Nil Then 
Print Info(Ptr) 

Else 

Case Result Of 

D_ .Name_Error : Writeln (' Error in file name'); 

D_Off _ Line : Writeln (' Volume off line'); 

D_Not _ Found : Writeln (' File not found'); 

D_Other : Writeln (' Miscellaneous error'); 

End; {cases} 

Writeln ; 

Repeat 

Write ('Continue ?'); 

Read (Ch); Writeln; 

Until Ch In ]'n','N','y','Y']; 

Writeln ; 

Release (Heap .Ptr); 

Until Ch In ['n', 'N']; 

End. {listtest } 


Function D_Change_Name 

(D_OLD_NAME, D_NEW_NAME : String; 

D_REMOLD : Boolean): D_Result; 
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D_Change_Name searches for the volume or file desig¬ 
nated by the file name contained in D_OLD_NAME 

and changes its name to the file name contained in 
D_NEW_NAME. 

D_Change_Name only changes one file name at a time, 

and thus does not accept file names containing wild 

cards; however, it can be combined with other Dir_Info 

and wild card routines to create user-defined file name 
changing routines that accept wild cards. 

D_Change_Name accepts the following parameters. 

• D_OLD_NAME—A string containing the name 

of the file to be changed. If the file name is invalid, 

D_Change_Name returns D_Name_Error. Note 

that wild card characters are treated literally. 

• D_NEW_NAME —A string containing the 

replacement file name. If the file name is invalid, 

D_Change_Name returns D_Name_Error. Note 

that wild card characters are treated literally. 

• If D_OLD_NAME contains an empty file title, 

D_Change_Name changes the name of the volume 

specified by D_OLD_NAME to the volume name 

in D_NEW_ NAME; any file title in 

D_NEW_NAME is ignored. If D_OLD_NAME 

contains a nonempty file title, D_Change_Name 

changes the name of the disk file specified by 

D OLD NAME to the file title in 

D NEW NAME; any volume name in 

D NEW NAME is ignored. If the file ID in 

D NEW NAME is empty, D Change Name 

returns D_Name_Error. 
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• D_REMOLD—If set to TRUE, D_REMOLD 

indicates that an existing file or volume designated 

by the file name in D_NEW_NAME can be 

removed in order to change the file name. If set to 
FALSE, the presence of an existing file or volume 

with the same name as D_NEW_NAME aborts 

the name change, and D_Change_Name returns 

D_Exists as a function result. 

• D_Change_Name returns a value of type 

D_Result. D_Change_Name can return all scalar 

values defined in D_Result; the values have the fol¬ 

lowing meanings. 

— D_Okay—No error. D_OLD_NAME was 

found and its name changed. 

— D_Not_Found—No such file/volume found. 

No match found for D_OLD_NAME. No 

change made. 

— D_Exists—The name change was blocked by 

the presence of an existing file with the same 
name as D_NEW_NAME. No change made. 

— D_Name_Error—Illegal file name syntax in 

D_OLD_NAME or D_NEW_NAME. No 

change made. 

— D_Off_Line—Volume off-line. The volume 

specified by D_OLD_NAME was not on-line. 

No change made. 

— D_Other—Unknown. D_Change_Name 

encountered an error it could not identify. No 
change made. 

Example Program 

The following program demonstrates how you might use 

D_Change_N ame. 
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Program chngtest; 

Uses 

(*$U WILD.CODE*) 

wild, 

(*$UDI H.INFO.CODE*) 

Dirlnfo; 

Var 

RemOld: Boolean ; 

Old, New: String; 

Ch : Char ; 

Rslt; I) Result; 

Begin {chngtest} 

Writeln CD ChangeNameTest— 

Repeat 

Writeln; 

Write!'Name to change : '); 

Readln(Old): 

Write!'New name : '); 

Readln(New); 

Write !Remove existing files (if any) of that name ? [y n}); 
Read(Ch); Writeln; 

RemOld := Ch In ['y'.'Y'J; 

CaseD ChangeName(Qld, New , RemOld) Of 
I) Okay :Writeln!' No error'); 

I) _ Off _ Line : Writeln!' Volume off line'); 

I) Name Error :Writeln!' Error in file name'); 

I) Not Found : Writeln !' File not found'); 

D_ Other :Writeln!' Miscellaneous error'); 

End; {cases} 

Writeln; 

Write !'Continue ? '); 

Read(Ch); Writeln ; 

Until Ch In ['n', 'N'J; 

End. {chngtest} 






















Wild Card File Name Change 

D_Change_Name does not accept wild card file name 

arguments; however, it can be combined with the pattern 

matching information returned by D_Dir_List to 

implement a wild card file name changing routine. (Note 
that this routine must use directory locks in multi¬ 
tasking environments.) 

For example, assume that you have the following files: 

TEST1.TEXT 

TEST12.CODE 

TEST.DATA 

You would like to change them to the following names: 

OLD1A.TEXT 

OLD12A.CODE 

OLDA.DATA 

This can be performed by using D_Dir_List to search 

for the file name TEST=. = . The pattern matching infor¬ 
mation returned by D_Dir_List can be used to create 

new file titles; in this case, TEST is replaced with OLD , 
and the first = is replaced with the catenation of the pat¬ 
tern matched by the = and the literal string A. The part 
of each file title matched by the period and the second = 

wild card is unchanged. D_Change_Name is called with 

the modified file title for each file matched by 
D_Dir_List. 

Example Program 

The following program demonstrates how you can use 

D_Change_Name and D_Dir_List when constructing 

a specialized file name changing utility. The program 
accepts a file name argument containing two = wild 
cards; for each file which matches the argument, the file 
title is changed by swapping the string patterns matched 
by the two = wild cards. 
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Program WildChng: 


Uses 

(*$UWILD.CODE*) 

wild, 

(♦SUDIR.INFO.CODE*) 

Dir Info; 

Var 

Heap Ptr : A Integer ; 

Typ : D _ NameTyp; 

Segs : Integer : 

Select : D_Choice; 

Volume, Name, Match :String; 

Result ; D Result; 

Ch :Char; 

Ptr : D_ListP; 

Procedure GiveChoice(Choice :String; Kind : I) Choice); 
Var 

Ch :Char; 

Begin 

Write r ', Choice,' ? '); 

Read(Ch);Writeln; 

If Ch In ('y\ 'Y'] Then Select := Selects Kind; 

End; { GiveChoice } 

Procedure Print Patterns!PatPtr : D PatRecP; 

Comp, Wild : String ) 

Var 

Count : Integer ; 

Begin [ Print Patterns J 
Count : = 1; 

Writeln !'type < cr> for patterns'); 

Readln ; Writeln ; 

Repeat 

Writeln l'Pattern ', Count. ' :'); 

With PatPtr A Do 
Begin 

Writelnl' Comp ; Comp); 

If CompLen <>0 Then 
Write! A ':|CompPos +9)); 

If CompLen 1 Then Write!’ A ’:(CompLen - D); 
Writeln; 

Writeln!' Wild : . Wild); 

Write!' A ':(W'ildPos + 9)); 

If WildLen > 1 Then Write ! A :(WildLen - 1)); 
Writeln; Writeln; 

End* 

PatPtr := Pat Ptr A .Next; 

Count := Count + 1; 

Until PatPtr = Nil 
End; {Print Patterns } 























Procedure Print InfolPtr : D_ListP; Want_Patterns : Boolean ; 

Volume, Name:String; 

Begin { Print Info } 

Repeat 

Writeln! MATCHF^D FILE 
With Ptr Do 
Begin 

Write! D _ Volume, 

If DZTIsBlkd Then 
If Length!D Title) > OThen 
Write ! D_Title); 

Writeln ; 

If Want Patterns And (D_ VPat < > ) Then 
Begin 

Writeln ; 

Writeln !' Volume patterns:'); 

Print Patterns(D_VPat, D Volume, Volume); 
End; 

If D_IsBlkd Then 

If W r ant_ Patterns And (D _ FPat < > Nil) Then 

Begin 

Writeln !' File name patterns:'); 

Print Pat terns! D FPat, D Title. Name); 
End; 

End { With Ptr A } 

Writeln; 

Write!'Type <cr> for rest of list'); 

Readln; Writeln ; 

Ptr := Ptr A .D „NextEntry; 

Until Ptr = Nil 
End; { Print Info } 

Procedure Change!Ptr : D _ ListP; Name :String); 

Var 

I, Posl, Lenl, Pos2, Len2, Last Pos, 

Mid_ Pos, Last Equal integer ; 

Patl, Pat2, Title. New : String ; 

Procedure Find . Equal(I) _ Title, Name : String ; 

Var Pat Ptr : I) _PatRecP; 

Var Pat: String ; 

Var Pos , Len : Integer . 

Begin { Find Equal } 

While !Name(PatPtr A .WildPos] <> '=') And 
(PatPtr A .Next <> Nil) Do 
PatPtr := PatPtr A .Next; 

W'ith PatPtr A Do 
Begin 

If Compl-en = 0 Then Pat : = " 

F21se Pat : = Copy (D_Title, CompPos, CompLen); 
Pos:= CompPos; 

Len := Compl^en; 

End; 

End; { Find__Equal } 
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Begin { Change } 

With Ptr A Do 
Begin 

Find Equal(D Title, Name. D_FPat, Patl, Posl, Lenl); 

If D FPat <> Nil Then 
Begin 

D_FPat := D_FPat A .Next; 

Find. Equal! I) Title, Name, D. FPat, Pat2, Pos2, Len2); 
New : = I) Title; 

Last _ Pos := Pos2 -I- Len2; 

Mid_Pos := Posl + Len2; 

Last. Equal := Last Pos — Lenl; 

For I ;= Posl To Mid Pos - 1 Do { 1st '=' } 

New|11; = Pat2[I - Posl + 1); 

For I := Mid Pos To Last. . Equal 1 Do 
Newjl] := D TitleJ I — Len2 — Lenl); 

For I := Last Equal To Last,. Pos — 1 Do { 2nd } 

New[I): = PatlJI — Last .Equal—1); 

New: = Concat(I) _ Volume. New); 

Title := ConcaUD Volume,D Title); 

Result := D_ ChangeN ame(Title, New , True ); 

Write(Title, > \ New); 

Case Result Of 

I). . .Name .Error : Write! ' Error in file name'); 

I) Off Line :Write!' Volume off line'); 

D _ Not Found : Write !' F’ile not found'); 

D_ Other : Write!' Miscellaneous error'); 

End; {cases} 

Writeln ; 

End; { if D FPat} 

End; { with } 

End; { Change } 

Function Display(S, Match, Volume, Name :String; 

Select: D Choice): I) ListP; 

Var 

Ch:Char; 

Ptr: D_ ListP; 

Want _ Patterns : Boolean ; 

Result: D Result; 














Begin { Display } 

WriteIn ; Writeln ( S); 

Write!' Display pattern matching information ? '); 
Read (Ch); Writeln ; 

Want Patterns := Ch In ['y', 'Y']; 

Result := D_ Dir List! Match, Select. Ptr. True ); 

If Ptr < > Nil Then 

Print_. Info!Ptr, W'ant_Patterns, Volume, Name) 

Else 

Case Result Of 

D Name Error :Writeln(' Error in file name'); 

I) _ Off _ Line : Writeln!' Volume off line'); 

D Not_Found :Writeln!' File not found'); 

D Other :Writeln(' Miscellaneous error'); 

End; {cases} 

Display := Ptr; 

End; { Display } 

Begin { WildChange } 

Writeln ; 

Repeat 

Mark (Heap. _Ptr); 

Select := [ ]; 

Write l'File title to match (must contain two " = '); 

Readln! Match); 

Result := I). .ScanTitle!Match, Volume, Name, Typ, Segs); 
Writeln !'Types [ y/n J:'); 

GiveChoice!'Directories'. (D _ Vol]); 

GiveChoice!'Text Files ', (I) _ Text)); 

GiveChoice!'Code Files ', |D _ Code)); 

GiveChoice!'Data Files )I) Data)); 

GiveChoice!'SVol Files ', )D_SVol)>; 

Ptr := I)isplay('01d Files Match, Volume, Name, Select); 
If Ptr < > Nil Then 
Begin 
Repeat 

Change! Ptr. N ame); 

Ptr := Ptr A .D_NextEntry; 

Until Ptr = Nil; 

Write !'Redisplay files? '); 

Read(Ch);Writeln; 

If Ch In )'y\ 'Y'J Then 
Ptr := Display!'New Files Match, 

Volume, Name, Select); 

End; 

Writeln ; 

Repeat 

Write !'Continue ? '); 

Read(Ch);Writeln; 

Until Ch In ('n'.'N'.'v'.'Y'); 

Writeln ; 

Release! Heap _ Ptr); 

Until Chlnl'n', 'N'); 

End. { WildChng ) 






















Function D_Change_Date 

(D_NAME : String; 

D_NEWDATE : B_DateRec; 

D_SELECT : D_Choice): D_Result; 

D_Change_Date changes the file date of volumes and 

files whose names match the file name argument con¬ 
tained in D_NAME. D_Change_Date accepts wild 

cards in its file name argument. If a volume date is 
changed, only the disk is updated. The disk must be 
rebooted if the new date is to be used. To change the inter¬ 
nal date, which will appear when D(ate is used in the filer, 
use the date access procedures within the SYS.INFO 
unit. 

D_Change_Date accepts the following parameters. 

• D_NAME—A string which contains a valid file 

name. The file name may contain wild cards. 

• D_NEWDATE—A record of type D_DateRec 

which contains the new date. A year value of 100 is 
not accepted by D_Change_Date in a new date. 

• D_SELECT—A set of file and/or volume. All scalar 

types except D_Free and D_Temp apply to 

D_Change_Date. Disk free spaces identified by 

the D_Free scalar do not contain file dates. Tempo¬ 

rary status for files is specified by a special value in 

the file date field. Thus, D_Free and D_Temp are 

ignored if they are included in D_SELECT. 
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D_Change_Date returns a value of type D_Result. 

D_Change_Date can return all scalar values defined in 

D_Result except D_Exists; the values are described in 

the following items. 

• D_Okay—No error. D_NAME was found, and 

D_NEWDATE was written to the directory for the 

specified file or disk volume. 

• D_Not_Found—No such file/volume found. No 

match found for D_NAME. No change made. 

• D_Name_Error—Illegal syntax in D_NAME. No 

change made. 

• D_Off_Line—Volume off-line. The volume speci¬ 
fied by D_NAME was not on-line. No change 

made. This error occurs only if the volume ID in 
D_NAME specifies a single volume which is off¬ 
line. If the volume name in D_NAME contains wild 

cards and does not match any on-line volumes, 
D_Change_Date returns D_Not_Found. 

• D_Other—Unknown error. No change made. 

D_Change_Date encountered an unidentified 

error which prevented successful completion of the 
operation. 

Example Program 

The following program demonstrates the use of 

D_Change_Date. 


4-41 






Program Date. Test; 

Uses 

(*$UWILD.CODE*) 

wild. 

(*$UDIR. INFO.CODE*) 
Dirlnfo; 


Var 

Result : I) Result; 

Ch :Char; 

M. D, Y : Integer ; 

NewDate : I). DateRec: 

Select : I) Choice; 

FileName :String; 

Procedure GiveChoiceiChoice rString; Kind : D ..Choice); 
Var 

Ch :Char; 

Begin 

Write r '.Choice,' ?'); 

Read (Ch); Writeln ; 

If Ch In ['y', 'Y 'J Then Select := .Select + Kind; 

End; { GiveChoice } 

Begin { Date_Test } 

Select := [ ]; 

Writeln ! 'D ChangeDate Test—'); 

Repeat 

Writeln ; 

Write !'File to change : '):Readln( FileN ame); 

Writeln!'Types ( v n ]:'); 

GiveChoice! Directories', [D _ Vol]); 

GiveChoice!'Text Files ', [D Text]); 

GiveChoice!'Code Files ', [D_Code]); 

GiveChoice! Data Files ', (I) Data]); 

GiveChoice!'SVol Files [D SVol]); 

GiveChoice!'SVol Files ', [D SVol]); 

Writeln !'New date :'); 

Write! Month [1 — 12]:'); Readln(M); 

Write!'Day [1 — 31]: ');Readln(D) 

Write !'Year ]0 — '); Readln (Y); 

With NewDate Do 























Begin 

Month := M; 

Day := I); 

Year := Y; 

End; { With NewDate } 

Writeln 

Result := D_ChangeDate) File Name, NewDate, Select); 

Case Result Of 

I) _Okay : Writeln) date changed'); 

I) _ Name_Error : Writeln )'error in file name'); 

I) _()ff _ Line : Writeln)'volume off line'); 

d Found : Writeln) file not found ); 

I) Other : Writeln( 'miscellaneous error'); 

End; { cases } 

Writeln; 

Write )'Continue ?'); 

Read (Ch); Writeln ; 

Until Ch In ['n'/N'J; 

End. { Date Test } 

Function D_Rem_Files 

(D_NAME : String; D_SELECT : 

D_Choice): D_Result; 

The D_Rem_Files function removes file objects whose 

names match the file name argument contained in 

D_NAME and types match the elements included in 

D_SELECT. The file name argument can contain wild 

cards. Disk files are permanently deleted from their direc¬ 
tories. Volumes are taken off-line, but not altered in any 
way; off-line disk volumes can be brought back on-line 
merely by referencing them, while off-line serial volumes 
remain inaccessible until the system is reinitialized. 
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D_Rem_Files accepts the following parameters. 


• D_NAME—A string containing the name of the 

file(s) or volume(s) to be removed. 

• D_SELECT—A set of file objects to be removed. 

The definition of the set is as follows: 


D_NameType = (D_Vol, D_Code, D_Text, 

D_Data, D_SVol, 

D_Temp, D_Free); 

D_Choice = Set Of D_NameType; 

All scalar types except D_Free apply to 

D_Rem_Files. Disk free space cannot be removed 

from the directory; thus, D_Free is ignored if it is 

included in D_SELECT. 


D_Rem_Files returns a value of type D_Result. 

D_Rem_Files can return all scalar values defined 

in D_Result except D_Exists; the values have the 

following meanings. 

• D_Okay—No error. D_NAME was found. If 

D_Vol is included in D_SELECT, and a volume 

matches the file name argument in D_NAME, the 

volume is taken off-line. If D_Text, D_Code, 

D_Data, D_SVol, or D_Temp are included in 

D_SELECT, disk files of those types which match 

D_NAME are deleted from their directories. 


• D_Not_Found—No such file/volume found. No 

match found for D_NAME. No change made. 




D_Name_Error—Illegal file name syntax in 

D_NAME. No change made. 
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• D_Off_Line—Volume off-line. The volume speci¬ 
fied by D_NAME was not on-line. No change 

made. This error occurs only if the volume ID in 
D_NAME specifies a single volume which is off¬ 
line. If the volume ID in D_NAME contains wild 

cards, but does not match any on-line volume, 
D_Rem_Files returns D_Not_Found. 

• D_Other—Unknown error. No change made. 

D_rem_Files encountered an unidentified error 

which prevented successful completion of the opera¬ 
tion. 

Example Program 


Program Rem_Test; 

Uses 

(*$UWILD.CODE*) 

wild, 

(*$UDIR. INFO.CODE*) 

Dirinfo; 

Var 

Result: D_Result; 

Select: D _ Choice; 

Ch rChar; 

Remfile: String ; 

Procedure GiveChoice(Choice ; String ; Kind : D _ Choice); 

Var 

Ch :Char; 

Begin 

Write r '.Choice,' ? '); 

Read (C h); Writeln; 

If Ch In ['y', 'Y'J Then Select := Select + Kind 
End; { GiveChoice } 
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Begin { Rem_Test } 

Select := [ ]; 

Writelnl'D RemFiles Test—'); 

Repeat 

Write('File(s) to remove :'); 

Readln(Remfile): 

Writeln !'Types [ y/n ]:'): 

GiveChoice('Directories', (D Vol]); 
GiveChoice('Temp Files ', [D Temp]); 
GiveChoice('Text Files [D Text]); 
GiveChoice('Code Files [D Code]); 
GiveChoice('Data Files (D Data]); 
GiveChoicel'SVol Files ', [D._.SVol]); 

Result := D RemFiles(Remfile, Select); 

Case Result Of 

I) Okay : Writeln('files removed'); 

I) Name Error : Writeln!'error in file name'); 

D Off_Line : Writeln! 'volume off line'); 

D _Not Found :Writeln!'file not found'; 

D _Other : \Vriteln('miscellaneous error'); 

End; { cases } 

Writeln; 

VVrite <'Continue ?'); 

Read(Ch); Writeln; 

Until Ch In ['n'.'N']; 

End. { Rem_Test } 


Procedure D_Lock 

D_Lock grants exclusive directory access rights to the 

task that executes it; however, a task may have to wait 
until another task releases the directory lock before it can 
continue execution past its call to D_Lock. 


NOTE 

D_Lock calls should always be matched with 

D_Release calls to prevent system deadlocks. 
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The Dir_Info routines D_Lock and D_Release are 

provided for use in multi-tasking environments. When 
used properly, they ensure mutually exclusive access to 
directory information. 

Procedure D_Release 

D_Release releases exclusive access rights to the direc¬ 

tory. Tasks already waiting for directory access are auto¬ 
matically awakened when the directory becomes 
available by a call to D_Release. 

Example Program 

The following program demonstrates the use of D_Lock 

and D_Release. 


Program Locktest; 

Uses 

(*$U WILD.CODE*) 
wild, 

(*$UDIR. INFO.CODE*) 

Dir Info; 

Const 

Stack_Size = 2000; 

Var 

Pid : Processed; 

Old, 

New : String ; 

Date: I) DateRec; 

M, D, Y integer ; 

Ch : Char ; 

Process Change And_Check(Old, New : String ; Date : 

I)_DateRec) Var 

Result: I) Result; 

Begin { Change^ And Check } 

D_ Lock; { beginning of critical section } 

Result :=D Changel)ate(01d, Date, [D. Vol..D SVol]); 

If Result = D _ Okay Then 

Result := D _ ChangeName(01d, New , True ); 

DRelease; { end of critical section } 

End; { Change And _Check } 
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Begin { LockTest} 

Repeat 

Write!'Old file name: 'I: 
Ileadln (Old); 

Write ! New file name: '); 
Readln ( New ); 

Writeln! 'New date:'); 
Write!' Month: '); 
Readln(M); 

Write!' Day:'): 
Readln(I)); 

Write !' Year: '): 
Readln (Y); 

With Date Do 


Begin 

Month := M; 

Day := D; 

Year := Y; 

End: 

Start !Change And . Check!Old.New, Date), Pid, 
Stack Size); 

Write!'Start another? '); 

Read(Ch); Writeln; 

UntifCh In |'n , N'|; 

End, JLocktest J 
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WILD CARDS (WILD) 


The unit WILD provides a wild card convention for pattern 
matching of string variables. Wild cards are special character 
sequences in a character string; they are named wild cards 
because of their ability to match whole classes of character 
sequences rather than a single character sequence. For instance, 
the string a= matches all character strings starting with the let¬ 
ter a because ( = ) is defined as a wild card that matches any char¬ 
acter sequence. 

Wild cards are useful in pattern matching situations where many 
character strings are to be matched with a single request. The p- 
System filer uses a set of wild card facilities in its directory opera¬ 
tions. Examples are given in the p-System manual that describes 
the filer operation. Because of the extra functions provided by 
this UNIT, there is not a direct correspondence between the filer 
and this UNIT. Where there are differences in the use of charac¬ 
ters, these are described. 

Special Wild Card Characters 

The following characters are defined as special charac¬ 
ters: 


question mark 

? 

equals sign 

= 

braces 

{ and } 

comma 

» 

hyphen 

- 

tilde 


percent sign 

% 


Special characters may only be used as parts of wild 
cards. However, a literal occurrence of a special character 
can be represented by a two character sequence consist¬ 
ing of a percent sign followed by the special character. A 
percent sign indicates that the following character is to 
appear literally in the character string; for instance, 
xx%=yy is treated as the literal character string xx=yy 
rather than a wild card string. 
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Examples of percent sign in wild cards: 


ab%?def 

ab{a—z, % = }de%%f 
ab%—def 


matches ab?def 

matches ab=de%f 

matches ab—def 


Question Mark Wild Card 

A question mark matches any single character. In 
the filer, the (?) is treated as an interactive query 
of an ( = ) wild card. This is one of the major dif¬ 
ferences in use of characters between this UNIT 
and the filer. 

Examples of ( ? ) wild card: 

Pattern: ab?def 

Matches: abbdef 


abrdef 


Nonmatch: 


abdef 

abjkdef 

abef 


Equals Sign Wild Card 

An equals sign matches any sequence of charac¬ 
ters, including the empty sequence. This is the 
same as the filer except that more than one ( = ) 
can appear in a wild card string. Examples of ( = ) 
wild card: 

Pattern: ab=def= 

Matches: abcdefg 


abdef 

abcccdef 


Nonmatches: 


abcef 
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Subrange Wild Card 


The subrange wild card matches a single charac¬ 
ter from the character set specified in the sub¬ 
range. The special characters, comma, hyphen, 
tilde, and braces, are used to construct subrange 
wild cards. 

A subrange wild card consists of a character set 
delimited by braces. A character set consists of a 
list of character items separated by commas. 

A character item is either a character or a charac¬ 
ter range (two characters separated by a hyphen). 
A character range implicitly specifies all charac¬ 
ters lying between the two characters. (Consult 
an ASCII table to determine the ordering of 
characters.) 

Character items preceded by tildes are called ne¬ 
gated items and are specifically excluded from 
the character set. A character range preceded by 
a tilde is entirely excluded from the character set. 
The list of character items is evaluated left to 
right. Characters specified by nonnegated items 
are included into the set; characters specified by 
negated items are excluded from the set. Thus, a 
character matches the subrange wild card if it 
matches one of the nonnegated items, but does 
not match any of the negated choices. For ex¬ 
ample, the subrange {a—z'vr} represents the set 
of characters from a to z, excluding r. 

NOTE 

Blank characters within subrange wild 
cards are ignored. Wild card characters 
can be specified in character sets with 
the percent sign notation described in 
the preceding paragraphs. 
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Examples of subrange wild cards: 


{a,b,c} 

{a—d,j,w—z} 

{a-z^j/Vx-y} 

Syntax for subrange wild card: 


wild-card 

item-list 

item 

char-item 

range 

char 

= {item-list} 

= item < , item > 

= [^] char-item 

= char/range 

= char — char 

= an ASCII character 


Examples of subrange wild card: 


Pattern: 

ab{a—r, ^)» 'Vkjdef 

Matches: 

abbdef 

abrdef 

Nonmatches: 

abjdef 

abkdef 

abzdef 


Function D_Wild_Match 

(WILD, COMP: String; 

Var PPTR : D_PatRecP; 

PINFO : Boolean) : Boolean; 




D_Wild_Match serves as a general purpose 

pattern matcher for string variables using the 
wild card conventions described above. The two 
main parameters are a wild card string, WILD, 

and a literal string, COMP. D_Wild_Match 

determines whether the literal string matches the 
wild card string. If the strings match, 

D_Wild_Match returns true; otherwise, it 

returns false. If PINFO is set to true, 

D_Wild_Match returns information (accessed 

through PPTR) that describes how the strings 
were matched. 

D_Wild_Match Parameters 

D_Wild_Match accepts the following parameters: 

• WILD—A string which can contain wild cards. 

• COMP—A literal text string. 

• PINFO-A Boolean. If set to TRUE, PINFO 
requests that pattern matching information be 
returned. 

• PPTR—Pointer of type D PatRecP. Depending on 

the value passed in PINFO, D_Wild_Match either 

sets PPTR to NIL or points it at a linked list of 
records containing pattern matching information. 

D_Wild_Match Pattern Matching Info 

If PINFO is set to TRUE, D_Wild_Match returns pat¬ 

tern matching information in PPTR. PPTR is a pointer 

(of type D_PatRecP) to a linked list of records which 

contain the starting positions and lengths of correspond¬ 
ing character patterns in WILD and COMP. 
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D_Pat_RecP is defined as follows: 


D_PatRecP 

D_PatRec 


AD_PatRec; 

Record 


CompPos, 


CompLen, 

WildPos, 


WildLen:Integer; 

Next:D_PatRecP; 

End; { D_PatRec } 


CompPos and WildPos are the starting positions of corre¬ 
sponding character patterns in COMP and WILD, 
respectively. CompLen and WildLen are the pattern 
lengths. Next points to the next pattern record in the list; 
it is set to NIL in the last pattern record. The patterns 
occur in the list in the order in which they were matched 
in the strings. 

If the strings do not match, or the list was not requested 
(that is, PINFO is set to false), PPTR is set to NIL. 

Example of pattern record list: 

WILD contains:'=ab{a—m} = f?' 

COMP contains: 'abcdefg' 

If PINFO is set to true, pattern record list returned is: 

1. WildPos = 1, WildLen = 1 
CompPos = 1, CompLen = 0 
('=' matches the empty string) 

2. WildPos = 2, WildLen = 2 
CompPos = 1, CompLen = 2 
('ab' matches 'ab') 

3. WildPos = 4, WildLen = 5 
CompPos = 3, CompLen = 1 
('{a—m}' matches 'c') 
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4. WildPos = 9, WildLen = 1 
CompPos = 4, CompLen = 2 
('^matches 'de') 


5. WildPos = 10, WildLen = 1 
CompPos = 6, CompLen = 1 
('f' matches 'f') 

6. WildPos = 11, WildLen = 1 
CompPos = 7, CompLen = 1 
('?' matches 'g') 


NOTE 

When the ( = ) wild card in WILD matches an 
empty string in COMP, CompLen is set to 0 
and CompPos is set to the position of the next 
pattern in COMP (that is, the position where a 
nonempty pattern would have occurred). Be 
sure to check the validity of CompPos indices 
before using them to reference characters in 
COMP; otherwise, range errors may occur. 

Example Program 

The following program is an example of a string compari¬ 
son routine that uses D_Wild_Match. The program 

reads two strings and prints the result of the comparison; 
if requested, it also prints information describing how the 
patterns matched. 
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Program Wild _ Test; 


Uses (*$U WILD.CODE*) 

wild; 


Var 

W. C : String: 

Ch ; Char . 

PatPtr : D PatRecP; 
Want Patterns Boolean; 


Procedure Print ..Patterns!PatPtr ; D _ PatRecP; 

C, W : String ); 

Var 

Count : Integer ; 

Begin \ Print _ Pat terns } 

Writeln ( type < cr> for patterns'): 

Readln ; Writeln ; 

Count;= 1; 

Repeat 

Writeln ( Pattern Count, ' ;'); 

With PatPtr Do 
Begin 

U riteln (' Comp : '. C); 

If CompLen < > 0 Then Write (' 'MCompPos + 9)); 

If CompLen > 1 Then Write- > I' ':(CompLen — - 1)); 

Writeln ; 

Writeln (' W'ild : W); 

Write (' MWildPos + 9)); * "N 

If WildLen > 1 Then Write I' MWildLen — 1)); 

Writeln ; Writeln ; 

End; 

PatPtr := PatPtr A .Next; 

Count := Count + 1; 

Until PatPtr * Nil; 

End; { Print. _ Patterns J 

Begin J WikL Test 1 
Repeat 

Writeln IWildCard Check - '); 

Write I 'Wild Card String ; '); 

Readln (W); 

Write ('Comparison String : '); 

Readln (C); 

Write I Do you want pattern matching information ? [y/nj "); 

Read (Ch»; 

Want Patterns := Ch In ['y'/Y'J; 

Writeln ; Writeln ; 

If D .Wild MatchlW. C. PatPtr. W ant .Patterns) Then 
Writeln ( A Match ) 

Else Writeln l No Match'); 

If Want Patterns And I PatPtr <> Nil) Then a 

Print .PatternslPatPtr, C, W); 

Write ('Continue ? [y n] '); 

Read (Ch); 

Writeln ; Writeln : 

Until Ch In('n', N |; 

End. { W'ild _ Test } 
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SYSTEM INFORMATION (SYS.INFO) 


Unit SYS.INFO is an easy way to access some of the system 
global information. SYS.INFO uses KERNEL.CODE in its 
implementation section. Although it is possible to access 
KERNEL.CODE directly, there are many variables that are 
normally not needed. If a user requires a different set, then 
another unit similar to this one can be easily constructed for the 
particular situation. 

In order to distinguish the variables defined by this unit, they 
have been prefixed with SI. Here are the SYS.INFO routines: 

Work Code File Name: 

Procedure SI_Code_Vid 

(Var SI_Vol: String); 

Procedure SI_Code_Tid 

(Var SI_Title : String); 

The preceding procedures return the volume name (SI_Vol) and 

the file name (SI_Title) of the system work code file. 

Work Text File Name: 

Procedure SI_Text_Vid 

(Var SI_Vol: String); 

Procedure SI_Text_Tid 

(Var SI_Title : String); 

The preceding procedures return the volume name (SI_Vol) and 

the file name (SI_Title) of the system work text file. 

System Volume: 

Function SI_Sys_Unit: Integer; 


4-57 





The SI_Sys_Unit function returns an integer function result. 

The device number of the drive containing the system volume is 
returned. 

Procedure SI_Get_Sys_Vol 

(Var SI_Vol: String); 

The preceding procedure returns the volume name (SI_Vol) of 

the current system volume. 

Prefixed Volume Name: 

Procedure SI_Get_Pref_Vol 

(Var SI_Vol: String); 

Procedure SI_Set_Pref_Vol 

(SI_Vol: String); 

The preceding procedures allow the current prefix volume to be 
read and set. 

System Date: 

Procedure SI_Get_Date 

(Var SI_Date: SI_Date_Rec); 

Procedure SI_Set_Date 

(Var SI_Date : SI_Date_Rec); 

The SI_Get_Date and SI_Set_Date procedures access and 

modify the system date. The date is passed as a record of type 

SI_Date_Rec. Changing the date will not change the date on 

the system disk. It will only change the date internally in the 
operating system. To change the date on the disk, use function 
D_Change_Date within the DIR.INFO unit. 

SI_Date_Rec = Packed Record 

Month: 0..12; 

Day: 0..31; 

Year: 0..99; 

End; 
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This record is used in the operating system to store dates. It is a 
packed record and only requires 16 bits. All date variables use 
this format. 


Program Sys Test; 

Uses {$USys.Info.Codej Sys Info; 

Var 

Ch: Char; 

Date: SI Date Rec; 

Vol, 

Title: String ; 

Begin 

SI_ Code Vid (Voll; 

SI Code Tid (Title); 

If Length (Title) < > 0 Then 
Writeln (The Work Codefile is Vol,Title) 
Else 

Writeln ('There is no Work Codefile/); 

SI Text Vid (Vol); 

SI Text Tid (Title); 

If Length (Title) < > 0 Then 
Writeln ('The Work Textfile is Vol,';' Title) 
Else 

Writeln (There is no Work Textfile.'); 

Writeln ; 

SI Get^Sys _ Vol (Vol); 

Writeln ( The System was booted on volume ', Vol, 
': on device \ SI _Sys Unit); 

SI Get Pref_Vol (Vol); 

Writeln ; 

Writeln (The Prefix volume is ', Vol,':'); 

Write ('New Prefix:'); 

Readln (Vol); 

Delete (Vol, Pos (':', Vol), 1); 

If Length (Vol) In (L.7) Then 
Begin 

SI_Set Pref_Vol (Vol); 

SI_Get_Pref_Vol (Vol); 

Writeln (The Prefix volume is Vol,':'); 

End {of If} 

Else 

Writeln ('No change made’); 
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Writeln ; 

SI Get Date (Date); 

Writeln ("Hu* current date is '), 

Date. Month. — Date. Day. — Date. Year); 

Repeat 

Write ( Set for tomorrow's date ? '); 

Read (Ch): 

Until Ch In [ y . Y . 'n\ V]; 

Writeln ; 

If Ch In|y, 'Y'] Then 
Begin 

Date.Day : = Date.Day 4 1; 

If (Date.Month In [1.3. 5. 7, 8. 10, 12]) And (I)ate.Day = 32) Or 
(Date.Month In [4, 6. 9. 11]) And (Date.Day = 31) Or 
(Date.Month = 2) And (Date.Day = 29) Then 
Begin 

Date.Day:+ 1; 

If Date.Month = 12 Then 
Begin 

Date.Year :*= Date.Year 4- 1; 

Date.Month ;= 1; 

End {of If =12) 

Else 

Date.Month:— Date.Month 41; 

End {of If Date.Month}: 

SI _ Set Date (Date): 

SI _ Get Date (Date): 

Writeln ( The new date is 

Date.Month, -Date.Day, -Date.Year); 

End {of If Ch} 

Else 

Writeln ('No change made ); 

End{ofSys Test}. 
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FILE INFORMATION (FILE.INFO) 


This unit provides an easy way to access information in the file 
information block (fib). It uses the system globals from 
KERNEL.CODE. Although it is possible for you to access this 
global data, it is easier to use this unit. In order to distinguish the 
names in this unit, they have all been prefixed with an F. 

Type F_File_Type = file; 

Because of a Pascal language restriction, it is necessary 

to declare files of type (f_file_type) that are passed on 

as parameters to these procedures. 

Function F_Open 

(var fid: F_File_Type):boolean; 

This function should be called before any of the following 
are used. This enables a check to be made on the status of 
a file. The function returns true if the file is open and false 
if it is not open. The following functions will not give the 
correct values if the file is not open. 

Function F_Length 

(Var Fid : F_File_Type): Integer; 

Returns the length (in blocks) of the file attached to the 
Fid identifier. If the file is not opened, the result is 
returned as zero. This only has meaning for files on stor¬ 
age volumes as the value returned is the number of blocks 
allocated to the file. 

Function F_Unit_Number 

(Var Fid : F_File_Type): integer; 

Returns the device number of the storage volume con¬ 
taining the file attached to the Fid identifier. If there is no * 
file opened to the Fid, the function result is zero. 
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Procedure F_Volume 

(Var Fid : F_File_Type; 

Var File_Volume : String); 

Returns the name of the volume containing the file 
attached to the Fid identifier. If the external file lacks a 

defined volume name, F_Volume returns a volume ID 

constructed from a device number (such as #4:). If there is 

no file opened to the Fid, the file_volume is set to a null 

string. 

Procedure F_File_Title 

(Var Fid : F_File_Type; 

Var File_Title : String); 

Returns the title (with suffix) of the file attached to the 
Fid identifier. If there is no file opened to Fid, or if the 

external file is a volume, then the File_title is set to a 

null string. 

Function F_Start 

(Var Fid : F_File_Type): integer; 

Returns the block number of the first block of the file 
attached to the Fid identifier. This only has meaning for 
files on storage volumes. If there is no file opened to Fid, 
the function result is zero. 

Function F_is_Blocked 

(Var Fid: F_File_Type): Boolean; 

Returns a boolean that is true if the file attached to the 
Fid identifier is located on a storage volume (or block- 
structured device). If there is no file opened for the Fid or 
if the device is not a storage volume, the function result is 
set to false. 




Procedure F_Date 

(Var Fid: F_File_Type; 

Var File_Date: F_Date_Rec); 

Returns a record indicating the last access date for the 
file attached to the Fid identifier. If there is no file opened 

to Fid, the File_Date is unchanged. The definition of 

F_Date_Rec type is: 

F_Date_Rec = Packed Record 

Month: 0..12; 

Day: 0..31; 

Year: 0..100; 

End; 


TIME DATE UNIT 

This unit allows a program to read or set the hardware internal 
date and time. (This is an extension to the p-System for the TI 
PC.) This unit is located in the system library and is referenced by 
the UCSD Pascal USES declaration. The unit requires six pa¬ 
rameters which are as follows: 


Parameters 

Range 

HOURS 

0-23 

MINUTES 

0-59 

SECONDS 

0-59 

HUNDREDTHS OF SECONDS 

0-99 

DATE 

0-9999 

FLAG 

0-3 


The time is kept in 24-hour format and date is simply a count 
of days since the clock was started. This date is not the same 
as the p-System date. When the system is booted, the time is 
set to 00:00:00:00 and the date is set to 0. 
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There is no range checking of values passed to the unit. There¬ 
fore, each parameter value must meet the range criteria listed 
above or results are unpredictable. The date is kept and updated 
by the Settime utility as the Julian date (1 . . 366). The system 
increments the date field by one every 24 hours. 

The procedure TIMEDATE( HOURS, MINUTES, SECONDS, 
HUNDSECS, DATE, FLAG), is used to read and set the time 
and date. This is accomplished by setting the FLAG parameter 
to one of the following values: 

GET TIME = 0 
SET TIME = 1 
GET DATE = 2 
SET DATE = 3 


The following example demonstrates calling the Time/Date unit. 


PROGRAM EXAMPLE; 

USES SYSTEMI)T; 

{ example of how to use system time/date unit 

Var Hr. Min, Sec, 

Hsec, Date, Fig : Integer; 

Begin { example } 

Hr := 9; 

Min := 30; 

Sec := 0; 

Hsec ;= 0; 

Date ;= 0; 

Fig := 1; 

{ set flag to set time } 

{ call TimeDate to set time } 

TIMEDATE(Hr, Min, Sec. Hsec, Date. Fig); 
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{ call TimeDate to get time } 

Fig := 0; { set flag to get time } 

TIMEI)ATE(Hr, Min, Sec, Msec, Date, Fig); 

WritelnlTime: '.Hr.';', Min. Sec, V.Hsec); 

{ call TimeDate to set date } 

Date := 30 { set to day of month } 

pig : = 3 ; { set flag to set date } 

TIMEDATE(Hr. Min. Sec, Hsec, Date. Fig); 

{ call TimeDate to get date } 

D ate : = 0; { clear date parameter } 

Fig :*s 2; { set flag to get date } 

TIMEDATE(Hr, Min, Sec. Hsec, Date, Fig); 
Writelnl'Date: '.Date); 


End. { example } 





5 


Debugging and Analysis 


Introduction . 5-3 

Using the Debugger . 5-3 

Entering and Exiting . 5-4 

Using Breakpoints . 5-5 

Viewing and Altering Variables . 5-6 

Viewing Text Files . 5-8 

Displaying Useful Information . 5-9 

Disassembling p-Code . 5-10 

Example of Debugger Usage . 5-11 

Symbolic Debugging . 5-12 

Symbolic Debugging Example . 5-14 

Summary of the Commands . 5-17 


5-1/5-2 





















INTRODUCTION 


The symbolic debugger is a tool for locating and correcting 
errors that might exist in your compiled programs on the 
Texas Instruments Professional Computer. You can call it from 
the command menu. It can also be invoked while a program is 
running (when a breakpoint is encountered). Using the symbolic 
debugger, you can display and alter memory, single-step 
p-code, and display and traverse markstack chains. 

To use the debugger effectively, you must be familiar with the 
UCSD p-machine architecture and understand the p-code oper¬ 
ators, stack usage, variable and parameter allocation, and so 
on. These topics are discussed in the UCSD p-System Internal 
Architecture , TI Part Number 2232400-0001. 


USING THE DEBUGGER 

There are no menus explaining the debugger commands because 
they would detract from any information displayed by the pro¬ 
gram being debugged. However, when a command is entered, the 
system displays several short prompts that may ask for informa¬ 
tion. 

Many of the debugger commands require two characters (such as 
LP for L(ist P(code, or LR for L(ist R(egister). To exit the pro¬ 
gram after entering the first character, press the space bar to 
recall the main mode of the debugger. 

A current compiled listing of the program is a helpful debugging 
tool. It helps you determine p-code offsets and similar informa¬ 
tion. 

The debugger is a low-level tool, and as such, you must use it with 
caution. If you use the debugger incorrectly, the p-System can 
fail. 
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Entering and Exiting 


Press D to call the debugger from the command menu. If 
you enter the debugger in a fresh state, the system dis¬ 
plays the following prompts. 


DEBUG [version #] 

( 

A fresh state means that the debugger was not pre¬ 
viously active, and no breakpoints are currently enabled. 
If you enter the debugger in a nonfresh state, only the left 
parenthesis (appears. 

Exit the debugger by pressing Q to call Q(uit, R to call 
R(esume, or S to call S(tep. The Q(uit option disables the 
debugger. If the debugger is called again, it returns in a 
fresh state. The R(esume option will not disable the 
debugger and execution continues from where it left off. 
The debugger is still active; and if it is called again, it is in 
a nonfresh state. The S(tep option executes a single p- 
code and automatically again calls the debugger in a non¬ 
fresh state. 

If a program is running under the debugger's R(esume 
command, it may force a return to the debugger by call¬ 
ing the HALT intrinsic. In fact, any run-time error causes 
a return to the debugger if the debugger is active while 
the program is running. 

You may memlock or memswap the debugger (see the 
descriptions of those intrinsics) by using the M(emory 
command at the outer level. ML memlocks and MS mem- 
swaps the debugger. 
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Using Breakpoints 


To enter the debugger while a program is running, but 
not alter the program’s code, use the debugger to set 
breakpoints. Press B to call the Breakpoint option and 
then use either the S(et, R(emove, or L(ist command. To 
set a breakpoint, press S (et after pressing Breakpoint. 
There are, at most, five breakpoints numbered zero 
through four. The system displays four prompts asking 
for information. The first prompt is: 

Set Break 

Enter a digit in the range 0 through 4 and press the space 
bar. The next prompt is: 

Segname ? 

Enter the name of the desired segment and press the 
space bar. The next prompt is: 

Procname or #? 

Enter the number of the desired procedure and press the 
space bar. The final prompt is: 

Offset tn 

Enter the desired offset within the procedure and press 
the space bar. The system sets a breakpoint; and if that 
segment, procedure, and offset are encountered while 
resuming execution, the debugger is automatically called 
again. 

Use a compiled listing of the program to determine the 
location of the breakpoint. If no compiled listing is avail¬ 
able, use the text file viewing facility. 

To set a breakpoint that differs only slightly from the one 
most recently set, press the space bar for the break num¬ 
ber or segment. The system uses the previous break¬ 
point’s information. For example, to break in the same 
segment and procedure, but with a different offset, enter 
a space for everything except the offset. 
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To remove a breakpoint, press Breakpoint; then press 
R(emove. The system displays the following prompt: 

Remove break U ? 

To remove a breakpoint, enter its number; then press the 

space bar. 

To list the current breakpoints, press Breakpoint and 
then press L(ist. 

Viewing and Altering Variables 

The V(ar command allows the system to display data 
segment memory. It is another two-character command 
that must be followed by G(lobal, L(ocal, I intermediate, 
E(xtended, or P(rocedure. If G(lobal or L(ocal is selected, 
the system displays the following prompt. 

Offset 

Enter the desired offset into the data segment. 

If intermediate is selected, the system displays the fol¬ 
lowing prompt. 

Delta Lex Leve l ? 


Enter the appropriate delta lex level for the desired inter¬ 
mediate variable. 

If E(xtended is selected, the system displays the follow¬ 
ing prompt. 

Seg #? Offset 

Enter the appropriate segment number and offset num¬ 
ber for the desired extended variable. 
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If Procedure is selected, the system may display an off¬ 
set within a specified procedure. The following prompts 
are displayed in sequence. 

Segment name 7 Procname or U ? Varname or Offset#? 

When any of these options are used, the system displays 
a prompt similar to the following line. 

(1) S=INIT P#1 V0#1 2 C1 A : 0B0553 43 41 4C 43 61 -SCALCa 


This example is a portion of the local activation record for 
segment INIT, procedure 1, variable offset 1, at absolute 
hexadecimal location 2C1A. Following this, eight bytes 
are displayed, first in HEX CODE and then in ASCII (a 
dash ( —) indicates that the character is not a printable 
ASCII character). 

To view surrounding portions of memory, press V(ar. 
After a line has been displayed by the V(ar command, a 
plus (+) or minus (—) may be entered. This displays the 
succeeding or preceding eight bytes of memory. 

The eight bytes that are currently displayed can be 
altered. If a is pressed, then the line can be altered in 
hexadecimal mode. If a \ #92 is pressed, then the line can 
be altered in ASCII mode. When altering in hexadecimal 
mode, any characters that are to be left unchanged can be 
skipped by pressing the space bar. In the ASCII mode, 
any characters to be left unchanged can be skipped by 
pressing the RETl key. 
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It is possible to change the frame of reference from which 
the global, local, and intermediate variables are viewed. 
This can be done by using the C(hain command. Press C. 
The U(p, D(own and L(ist options are available. If L is 
pressed, all of the currently existing mark stack control 
words are displayed, beginning with the most recently 
created one. An entry in the list resembles the following 
line. 

(ms) S=HEAPOPS P#3 0#23 msstat=347C msdyn=F0A0 msipc=01DA 

msenv=FEE8 


This corresponds to a mark stack control word with the 
indicated static link (msstat), dynamic link (msdyn), 
interpreter program counter (msipc), and erec pointer 
(msenv). The indicated segment (HEAPOPS), procedure 
(#3), and offset (#23) are the return point for the proce¬ 
dure call which created the MSCW. 

If the U(p or D(own options are used, the frame of refer¬ 
ence moves up or down one link and the frame of reference 
for variable listings (using the V command) changes 
accordingly. 

Viewing Text Files 

To view a text file from the debugger, press F to call the 
F(ile command. The system displays the following 
prompt: 

Filename? First line #? Last line # ? 


Enter the name of the text file to be viewed followed by 
pressing the space bar. The .TEXT portion of the file 
name is optional. Then enter the first and last line num¬ 
bers that delimit the portion of text that you wish to 
view. This command lists as many lines as possible in the 
window from first line to last line of the indicated file. 
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The F(ile command is useful for debugging (especially 
using symbolic debugging) when a hard copy of the rele¬ 
vant compiled listing is not available. This command 
enables you to view source files on disk and disk files con¬ 
taining compiled listings without leaving the debugger. 

Displaying Useful Information 

Whenever control is returned to the debugger (that is, 
after a single step operation, or when a breakpoint is 
encountered), it displays various information if it is 
desired. This information includes p-machine registers, 
the current p-code operator, the information in the cur¬ 
rent markstack, or any specified memory location. In 
order to select which information is displayed, use the 
E(nable mode. After pressing E, the following options are 
available at the command level, Register, P(code, 
M(arkstack, A(ddress, and E(very (all of the preceding). 
Any or all of these options may be enabled at the same 
time. 

If Register is enabled, a line is displayed after each single 
step. The following line is an example of that display. 

(rg) mp=F082 s p = F 0 9 C erec=FEE8 seg=9782 i p c = 0 1 C 3 t i b = 0 4 9 3 

rdyq=2EBC 


If P(code is enabled, a line such as the following is dis¬ 
played after each step: 

(cd) S = HEAP0PS P#3 0#23 LLA 1 

If M(arkstack is enabled, a line like the following is dis¬ 
played after each step: 

(ms) S=HEAP0PS P # 3 0 # 2 3 msstat=347C msdyn=F0A0 msipc=OlDA 
msenv=FEE8 


If A(ddress is enabled, the system generates a display 
like the following line. 

(a) S = HEAP0PS P#3 0#23 2C1A: 0B0553 43 41 4C 43 61 -SCALCa 
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To initialize this address to a given value, use A(ddress 
mode at the outer level. Press A(ddress and the system 
displays the following prompt. 

Address ? 

Enter the absolute address in hexadecimal. The system 
displays eight bytes starting at that address. Also, that 
address is now displayed if the E(nable A(ddress option is 
on. 


Enabling E(very causes all of the above options to be 
enabled. 

The Disable mode disables any of the options just 
described. The L(ist mode lists any of the above options. 

Disassembling P-Code 

At the debugger’s outer level, there is a p-code option 
that displays the p-code mnemonics for selected portions 
of code. This option asks for: 

Segname? 

Procname or /I’ 

Start Offset U? and End Offset #? 

The indicated portion of code is then disassembled. This 
may be useful during single-step mode if you wish to look 
ahead in the p-code stream. This mode can be exited 
before it reaches the ending offset by pressing the BRK/ 
PAUSE key (BRK is the upper case version of this key); 
control returns to the debugger. 
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Example of Debugger Usage 

Suppose the following program is to be debugged: 


Pascal Compiler IV.0 


1 0 0:d 1 {$L LIST.TEXT} 

2 2 l:d 1 PROGRAM NOT_DEBUGGED; 

3 2 l:d 1 VAR I,J,K:INTEGER; 

4 2 l:d 4 Bl,B2:BOOLEAN; 

5 2 1:0 0 BEGIN 
621:10 I: = 1; 

7 21:13 J:=l; 

8 2 1:16 IF K < > 1 THEN WRITELN ('Whats wrong?'); 

9 2:0 0 END. 


End of Compilation. 


First we enter the debugger and set a breakpoint at the 
beginning of the IF statement: 


(BS) Set break #? 0 Segname 7 N0TDEBUG Procname or #? 1 Offset #?6 
(EP) 

(R) 


After setting the breakpoint we enable p-code (EP) and 
resume (R). Now we execute the program above, and 
when it reaches offset 6, the debugger is entered. We 
single-step twice: 


Hit break HO at S = N0TDEBUGP#1 0=6 
(cd) S = N0TDEBUG P#1 0#6 SLD01 
Ccd) S = N0TDEBUG P#1 0#7 SLDC1 
(cd) S = N0TDEBUG P#1 0#8NEQUI 

We see that our first single-step did a short load global 1. 


NOTE 

This put K on the stack. K is not global 3; I is 
global 3, J is global 2, and K is global 1. Every 
string of variables (such as /, J, and K in a dec¬ 
laration) is allocated in reverse order. Boolean 
Bl, which follows, is at offset 5, and B2 is at 
offset 4. Parameters, on the other hand, are 
allocated in the order in which they appear. 
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The second single-step did a short load constant 1 onto 
the stack. Now do an integer comparison ( < > ). This is 
where the error appears; so look at what is on the stack 
before doing this comparison: 

(LR) 

(rg) mp=EB62 sp = EB82 erec = . . . 

(A ) Address? EB82 

(a) EB82 : 01 00 C5 14 . . . 

You list the registers and then look at the memory 
address to which register sp points. You discover a 1 on 
top of the stack (01 00: this is a least-significant-byte-first 
machine) followed by a word of what appears to be non¬ 
sense. This leads you to suspect that K was not initial¬ 
ized. Looking over the listing, you quickly realize that 
this is the case. 


SYMBOLIC DEBUGGING 

The symbolic debugging feature allows specification of variables 
by name, rather than p-code offset. Also, breakpoints and por¬ 
tions of code to be disassembled can be indicated by procedure 
name and line number, rather than procedure number and p-code 
offset. 


A current compiled listing of the code in question is still essential 
for serious debugging efforts. 


To use symbolic debugging, it is necessary that the code being 
debugged is compiled with the $D+ option. The $D+ option, 
which defaults to $D —, instructs the compiler to output symbolic 
debugger information for those portions of a program that are 
compiled with $B+ turned on. Once a program is debugged, it 
should be recompiled without symbolic debugger information, 
because this information increases the size of the code file. 
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Using symbolic debugging, breakpoints can be specified by pro¬ 
cedure name and line number for all statements covered by the 
$D+ option. The Breakpoint command requests: 

Procname or #? 

Enter the first eight characters of the procedure name. The next 
line displayed is: 


First# Last# Line#? 


The underlines actually are values that define the range of line 
numbers available to you within the specified procedure. (These 
line numbers appear on compiled listings.) Enter the desired line 
number for the breakpoint. 

Variables within a given routine can be specified by name (rather 
than data segment offset number) if at least one statement within 
that routine is compiled with $D + . The V(ar command allows 
specification of G(lobal, L(ocal, intermediate, or Procedure vari¬ 
ables in this manner. E(xtended variables are not allowed to be 
specified symbolically. The V(ar command prompts: 

Varname or Offset # 7 

You can enter the first eight characters of the declared identifier. 
A line similar to the following appears: 

( 1) S = I N I T P = FILLTABL V = TAB LEI 2C1A: OB 05 53 43 41 4C 43 61 - 

SCALCa 

The segment is INIT; the procedure is FILL_TABLES; and the 

variable is TABLE 1. 

Similarly, the code to be disassembled by the p-code command 
can be specified symbolically for all portions of code covered by 
the $D+ option. 

This command requests: 

Procname or #? 
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Enter the first eight characters of the procedure name. The sys¬ 
tem displays the following prompt: 


First# Last# Start Line# 7 End Line#? 



The underlines are actually the boundaries that are available to 
you. You should enter the desired starting and ending line num¬ 
bers. The specified code is then disassembled. 


Symbolic Debugging Example 


To use symbolic debugging, some part of a Pascal compi¬ 
lation unit must be compiled with the {$D4~} compile¬ 
time directive. After this code has been generated, it is 
possible to reference variables and procedures by name 
rather than offset. The following example is a small 
Pascal program that has been compiled with the D 
option. 


ascal Compiler 

IV. 1 c5s-4 3/4/82 

1 

0 

0:d 

1 

{$D+} 

2 

2 

l:d 

1 

program example; 

3 

2 

l:d 

1 

var a, b,c: integer; 

4 

2 

l:d 

4 


5 

2 

l:d 

4 

procedure set_c. 

| 

2 

2:d 

1 

var d:boolean; 

7 

2 

2:0 

0 

begin 

8 

2 

2:1 

0 

d:=a> b; 

9 

2 

2:1 

5 

if d then 

10 

2 

2:2 

8 

c:=a*b; 

11 

2 

1:0 

0 

end; 

12 

2 

1:0 

0 


13 

2 

1:0 

0 

begin 

14 

2 

1:1 

0 

a:=0; 

15 

2 

1:1 

3 

b:=5; 

16 

2 

1:1 

6 

set _ c _ if _ d; 

17 

2 

:0 

0 

end. 


End of Compilation. 
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The following listing is an example of a debug session. 


Debug [xl5] 

(BS) Segname= EX A M PLE Procnameor # = SETCIFD 
symbolic seg not in mem Line#? 8 
(R) 

Hit break#0 at S=EXAMPLE P=SETCIFD L#8 
(BS) Segname = EXAMPLE Procnameor # = SETCIFD 
First#8 Last# 10 Line#? 9 

(R) 

Hit break #1 at S=EXAM PLE P=SETCIFD L#9 
(VL) Varname or offset#? D 

(1) S=EXAMPLE P=SETCIFD V = D E7B2 : 0000 9448 BEE7 190C-H- 

(Q) 

The first time the debugger is entered, the program exam¬ 
ple is not in memory and, hence, the symbolic segment is 
not in memory. However, a breakpoint can still be set 
symbolically providing you know on which line number to 
stop. For the second breakpoint, the symbolic segment is 
in memory; because of this, its first and last line numbers 
are given. 


NOTE 

The variable D was accessed symbolically, and 
its contents are displayed. 

If you try to access symbolically when the actual code 
segment is in memory and its symbolic segment counter¬ 
part is not present, the system displays the error message 
symbolic seg not in mem . Use the Z command in the 
symbolic debugger to find out if symbolic information is 
available for a particular segment. 
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The Z command lists all of the principal segments with 
their environment list. For example, the following 
example is a partial list of the principal segments 
(EDITOR and EXAMPLE) and their environments. 
The lowercase name example is the symbolic segment 
for EXAMPLE. The existence of example indicates 
that symbolic debugging information is available for at 
least one procedure in EXAMPLE. 
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SUMMARY OF THE COMMANDS 


A(ddress 

Displays a given address. 

Breakpoint 

Segment, procedure and offset must be 
specified. 

S(et 

Allows a breakpoint (0 through 4) to be set. 

R(emove 

Allows a breakpoint to be removed. 

L(ist 

Lists current breakpoints. 

C(hain 

Changes frame of reference for V(ariable 
command. 

U(p 

Chains up mark stack links. 

D(own 

Chains down mark stack links. 

L(ist 

Lists current mark stacks. 

F(ile 

Allows viewing of text files. 

E(nable 

Enables the following to be displayed. 

Disable 

Disables the following from being displayed. 

L(ist 

Lists the following. 

R(egister 

The registers: mp, sp, erec, seg, ipc, tib, 
rdyq. 

P(code 

Current p-code mnemonic. 

M(arkstack 

Mark stack display. 

A(ddress 

A given address. 

E(very 

All of the above. 

interactive 

Interacts with the performance monitor. 


5-17 




M(emory 


L(ock 

Memlocks the debugger. 

S(wap 

Memswaps the debugger. 

P(code 

Disassembles a given procedure. 

Q(uit 

Quits the debugger, fresh state if re-entered. 

R(esume 

Exits debugger, debugger remains active, 
nonfresh. 

S(tep 

Single steps p-code and returns to debugger. 


V(ariable 


G(lobal 

Displays global memory. 

L(ocal 

Displays local memory. 

I(nter 

Displays intermediate memory. 

P(roc 

Displays data segment of given procedure. 

E(xtended 

Displays variables in another segment. 

Z(seglist 

Displays segment lists. 
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INTRODUCTION 


The UCSD p-System’s utilities are various precompiled programs 
that can assist you in various ways. Most of the utility programs 
included here are useful during program development. The utili¬ 
ties covered in this chapter are: 

• The Decode utility which displays the content of code files 
in a meaningful fashion. 

• The Library utility which is used to place separately com¬ 
piled units into the client’s code file or into library files. 

• The Native Code Generator which converts portions of a 
p-code file into machine code. 

• The Patch utility which enables you to view the internal 
content of any sort of file. 

• The Print Spooler utility which allows you to print files as 
you are using the p-System normally. 

• The Real Convert utility which can improve the perfor¬ 
mance of large programs which use several real constants. 

• The XREF utility which is useful for analyzing Pascal 
programs. 

DECODE 

The decoder utility, called DECODE.CODE, provides access, in 
symbolic form, to all useful items contained in code files. The fol¬ 
lowing information is available. 

• Names, types, global data size, and other general informa¬ 
tion about all code segments in the file. 

• Interface section text, if present, for all units in the file. 
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• Symbolic listing of any (or all) p-code procedures in any (or 
all) segments of the file. 

• Segment references and linker directives associated with 
code segments. 

The decoder should be used whenever you want detailed knowl¬ 
edge of the internal contents of a code file; for instance, an imple¬ 
mentor of a p-machine emulator decodes test programs so that 
the object code can be executed and understood step-by-step. You 
should refer to UCSD p-System Internal Architecture , if detailed 
use of the decoder is planned. 

If a program uses a UNIT, the UNIT is decoded only if it is 
within the host file; DECODE will not search the disk for UNITs 
to decode. Assembly routines linked into a higher-level host will 
not be disassembled when the host is decoded. 

When the system executes DECODE, the first prompt asks for 
the input code file (if necessary, the suffix .CODE is automati¬ 
cally appended). The next prompt asks for the name of a listing 
file to which DECODES output may be written. This may be 
CONSOLE: (indicated by pressing the RETURN key), 
REMOUT:, PRINTER:, or a disk file. The system then displays 
the following menu: 

Segment Guide: Adi), # (dct index), D(ictionary), Q(uit) 


The following items explain the DECODE options. 


Dictionary Displays the code file’s segment dictionary. 

A(ll Disassembles all segments in the code file. 


#(dct index) 


Q(uit 


A number of a dictionary index followed by 
pressing the RETURN key disassembles a 
given segment, if present. 

Exits the decoder. 
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DECODE Programming Example 

Given the following Pascal program: 


1 


0:d 

1 {$L LISTl.TEXT} 

2 


l:d 

1 PROGRAM DEMO; 

3 


l:d 

1 VAR LINTEGER; 

4 


l:d 

2 

5 


l:d 

2 SEGMENT PROCEDURE ADDI; 

6 

3 

1:0 

0 BEGIN 

7 

3 

1:1 

0 I: = I + I; 

8 

3 

1:0 

5 END; 

9 

3 

1:0 

7 

10 

2 

1:0 

0 BEGIN 

11 

2 

1:1 

0 I:=50; 

12 

2 

1:1 

4 REPEAT 

13 

2 

1:2 

4 ADDI; 

14 

2 

1:1 

7 UNTIL 1=400; 

15 


:0 

14 END. 


DECODE displays a prompt asking for input and listing 
file names. Then, if you press to call the Dictionary 
option, the system displays the following listing. 
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G> 

05 


INX NAME START SIZE VERSION M. 


0: DEMO 2 

1: ADDI 1 

2: 

3: 

4: 

5: 

6 : 

7: 

8: 

9: 

10 :: 

11 :: 

12 :: 

13:: 

14:: 

15:: 

(C): 


20 IV_0 M. 

14 IV_0 M 


Sex: LEAST significant byte first 

Next Page: 0 

Segment Guide: A(ll, #(dct index), Dictionary, Q(uit 




TYPE 


PSEUDO 

PSEUDO 


SG# SEG_TYPE 


FMY_NAME or 


RL 


DSIZE 


SGRF HSG TS 


2 PROG SEG R 

3 PROC SEG R 

NO _ SEG 

NO_SEG 

NO _ SEG 

NO_SEG 

NO_SEG 

NO_SEG 

NO _ SEG 

NO _ SEG 

NO _ SEG 

NO_SEG 

NO _ SEG 

NO _ SEG 

NO _ SEG 

NO _ SEG 


1 

DEMO 


0 


) 


) 







The A(ll options produces the following disassembly. 


Constant pool for segment DEMO 
Block: 2 Block offset: 0 Seg offset: 0 

0: 1700 0000 4445 4D4F 2020 2020 0100 1400 0400 0000 -DEMO 

10: 0000 

Block: 2 Block offset: 40 Seg offset: 40 

0:0100 0000 0C00 - 

Segment:DEMO Procedure: 1 


Block: 1 Block offset: 

26 Seg offset: 

26 

Data size: 

0 

Exit IC: 38 


Offset 


Hex code 

0(000) 

LDCB 

50 

8032 

2(002) 

SRO 

1 

A501 

4(004) 

SCXGADDI 1 

7201 

6(006) 

SLDO 

1 

30 

7(007) 

LDCI 

400 

819001 

10(00A) 

EFJ 

4 

D2F8 

exit code 
12(000 

RPU 

0 

9600 


Constant pool for segment ADDI 
Block: 1 Block offset: 0 Seg offset: 0 

0: 1300 0000 4144 4449 2020 2020 0100 1000 0400 0000-ADDI 

10:0000 


Block: 1 Block offset: 32 Seg offset: 32 

0:0100 0000 0C00 
Segment: ADDI Procedure: 1 


Block: 1 Block offset: 

26 Seg offset: 

26 

Data size: 0 

Exit IC: 30 


Offset 


Hex cod 

0(000): SLDO 

1 

30 

1(001): INCI 


ED 

2(002): SRO 

1 

A501 

exit code: 

4(004): RPU 

0 

9600 
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Dictionary Display 


DECODE’s D(ictionary option displays the code file 
segment dictionary. The following items describe the 
information that is displayed. 


Inx (Index) 


Name 

Start 


DECODES name for each segment; 
individual segments may be disassem¬ 
bled by entering their number and 
pressing the RETURN key; for exam¬ 
ple, pressing 0 and then pressing the 
RETURN key for this sample causes 
only DEMO to be disassembled. 

Contains the names of each segment. 

Contains each segment’s starting 
block (relative within the code file). 


Size The length in words of each segment. 

Version The UCSD p-System version number 

of the segment. 


M_TYPE is the machine type. Usually this is 

M_PSEUDO, indicating a p-code segment, but assem¬ 

bled segments indicate a given machine. Other possible 

values for M_TYPE are M_6809, M_PDP, M_8080, 

M_Z_80, M_GA_440, M_6502, M_6800, M_9900, 

M_8086, and M_68000. 


SEG_TYPE can be NO_SEG, PROG_SEG, 

UNIT_SEG, PROC_SEG, or SEPRT_SEG. 

NO_SEG is an empty segment slot, PROG_SEG is a 

program segment, UNIT_SEG is a UNIT segment, 

PROC_SEG is a SEPARATE routine segment, and 

SEPRT_SEG is an assembled segment. 
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The RL columns indicate whether or not the segment is 
relocatable and whether it needs to be linked. An R indi¬ 
cates a relocatable segment. An L indicates a segment 
that must be linked. 

If the segment is declared within a program or unit, then 

the FMY_NAME column contains its family name, that 

is, the name of the program or unit. Otherwise, the 
DSIZE SGRF HSG columns are displayed and contain, 
respectively, the compilation module’s data size, segment 
references, and the maximum number of segments. 

At the bottom of the screen, (C): is followed by whatever 
copyright notice the code file may have. The next line 
indicates the byte sex of the code file. The menu is the 
last line on the display unit. 

On the same line, the block number of next portion of the 
dictionary is displayed after Next Page:. (In this example, 
the segment dictionary is entirely contained in block zero 
so the next page is zero. The last portion of the segment 
dictionary always points back to block zero.) 

Disassembled Listing 

The first portion of a disassembled listing shows the 
housekeeping information at the beginning of a code 
segment. The block number of this information is given. 
(Code files start at block zero.) The block offset and seg¬ 
ment offset are always zero. The information occupies the 
first 11 words (0 through 10) of the segment. This house¬ 
keeping information (which is described in the UCSD 
p-System Internal Architecture reference manual) in¬ 
cludes such things as the segment name, byte sex indi¬ 
cator word, part number, and so forth. To the right, the 
same information is displayed as ASCII characters 
when printable, and as dashes when nonprintable. (The 
segment name is usually the most obvious part of this 
display.) 
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The next few lines have the same format and display the 
constant pool. The block offset and segment offset are 
always nonzero for the constant pool. They represent the 
offset, in bytes, of the constant pool from the beginning 
of the block and the beginning of the segment, respec¬ 
tively. String constants and character type constants are 
usually easy to pick out in the ASCII display to the right. 

The disassembled code itself is displayed by procedures. 
The block number, block offset, segment offset, data size, 
and Exit IC are displayed. (Data size and Exit IC are 
described in the UCSD p-System Internal Architecture 
reference manual.) The OFFSET column shows the off¬ 
set in bytes from the front of the procedure (the count is 
in both decimal and hexadecimal). Then the p-code mne¬ 
monic is displayed; followed by the operands, if any; and 
finally, the HEX CODE for that particular instruction. 

The OFFSET column corresponds to the fourth column 
in a compiled listing. 

Jump operands are displayed as offsets relative to the 
start of the procedure, rather than I PC-relative (I PC is 
the instruction program counter). This is to make the 
disassembly more readable. Thus, the operand shown is 
the offset of some line; in the example, the equal false 
jump (EFJ) on line 10 shows 4, which means line 4 —the 
SCXG instruction. The HEX CODE indicates that the 
offset is actually F8 (or -8), which is IPC-relative. 

If a single segment were to be disassembled (rather than 
using the A(ll) command), a line similar to the following 
would be displayed. 

" \ 


There are 1 procedures in segment DEMO. 

Procedure Guide: A(11), # (of procedure), L(inkerinfo), 
CConstant pool), SCegment references), 

I(nterface text), Q(uit) 








Selecting A(ll) disassembles all of the procedures in the 
segment (in the example there is only one). Entering the 
number of a procedure, followed by pressing the 
RETURN key, disassembles that procedure. If present, 
L(inker information, S(egment references, and interface 
text may also be displayed. 


For example, if the segment is a unit with interface text 
and you press I, the following listing may be displayed. 

Interface text for segment SOMEUNIT: 

PROCEDURE A _ PROC; 

PROCEDURE ANOTHER PROCCI:INTEGER); 

FUNCTION A _ F U NOTION:BOO LEAN ; 

IMPLEMENTATION 


If the segment had references to other segments and you 
press S, the following listing may be displayed. 


\ 


Segment references list for segment KERNEL: 

5: SYSCMND 
4: DEBUGGER 
3: FILEOPS 
2: SCREENOP 
0 : 


14 : *** 

13: CONCURRE 
12: PASCALIO 
11:HEAPOPS 
10: STRINGOP 
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If the segment had linker information and you press L, 
the following listing may be displayed. 



THE LIBRARY UTILITY 

LIBRARY.CODE is a utility program that allows you to group 
separate compilations (units or programs) and separately assem¬ 
bled routines into a single file. A library is a concatenation of 
such compilations and routines. Libraries are a useful means of 
grouping the separate pieces needed by a program or group of 
programs. Manipulating a single library file takes less time than 
if the various pieces it contains were each within an individual 
file. Libraries generally contain routines relating to a certain area 
of application; they can be used for functional groupings much as 
units can. Thus, you might want to maintain a math library, a 
data file-management library, and so forth—each of these 
libraries could contain routines general enough to be used by 
many programs over a long period of time. 

Individual programs might also take advantage of the library 
construct. If a program uses several units suitable for compiling 
separately, but the units themselves are too small to warrant 
putting each into its own file, you would want to construct a 
single library containing all of those units. 

Even if a file contains only a single unit or routine, it is treated as 
a library when the unit or routine is used by some external host. 

Library is useful for putting units into SYSTEM.LIBRARY or 
other libraries and grouping assembly routines together. 
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This section uses the term compilation unit. A program or unit 
and all the segments declared inside it are called a compilation 
unit. The segment for the program or unit is called the host seg¬ 
ment of the compilation unit. Segment routines declared inside 
the host are called subsidiary segments. Units used by the host 
are not segments belonging to that compilation unit. Units used 
by the compilation unit generate information in the host segment 
called segment references. The segment references contain the 
names of all segments referenced by a compilation unit, and the 
operating system uses this information to set up a run-time 
environment. 

Some routines called from hosts exist in units in the operating 
system, and therefore appear in segment references, even though 
there is no explicit USES declaration. For example, WRITELN 
resides in the operating system UNIT PASCALIO, so the name 
PASCALIO appears in the segment references of any host that 
calls WRITELN. 

Using Library 

When Library is executed, it displays a prompt asking for 
an output file name. The file name must end in .CODE. 
Library removes an old file with the same name as the 
new library. 

Library then displays a prompt asking for the input file 
name. .CODE is automatically appended. 


6-13 




Library Example 

You specify SCREENOPS.CODE as an input file. 
Library displays the following listing. 



The preceding display shows that the file SCREENOPS 
consists of a unit. There are four possible types of code 
that can occupy the 16 slots in a library: units, programs, 
segment routines, and assembled routines. Library dis¬ 
plays the type, along with the name and length (in words) 
of each module. 


Library’s menu shows the various commands available. 


The N(ew command displays a prompt asking for a 
new input file. 


The A(bort command stops Library without saving 
the output file. 


The Q(uit command stops Library and saves the 
output file. Then Library displays the prompt, 
Not ice?, at the top of the display unit. Enter 
copyright notice and press the RETURN key. It is 
placed in the output file’s segment dictionary. 
Pressing the RETURN key without entering a copy¬ 
right notice exits Library without writing a copy¬ 
right notice. 
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• The T(og command toggles a switch that determines 
whether or not INTERFACE parts of units are 
copied to the output file. 

• The R(efs command lists the names of each entry in 
the segment reference lists of all segments currently 
in the output file. The list of names also includes the 
names of all compilation units currently in the out¬ 
put file, even though their names may not occur in 
any of the segment references. 

The remaining five commands allow code segments to be 

transferred from the input file to the output file. 

• A given slot can be transferred to the output file by 
typing a digit (zero through nine). Library then dis¬ 
plays a prompt: Copy from slot#? along with 
the digit just entered. If that is the name of the slot, 
press the space bar. If that is the first digit of a two- 
digit slot number, enter the second digit and press 
the space bar. Library confirms the entry before 
actually copying code. Press the BACKSPACE key 
to correct errors. If you press the RETURN key 
without entering a number, the copy does not hap¬ 
pen and Library redisplays its menu. 

If the destination slot in the output file is already 
filled, the system displays a warning and no copy 
takes place. If an identical code segment is already 
present anywhere in the output file, the new code 
segment is copied anyway. 

• The E(very command copies all of the codes in the 
input file to the output file. If, for any code segment, 
the corresponding slot in the output file is already 
filled, then Library searches for the next available 
slot and places the code there. If, for any code seg¬ 
ment, an identical code segment already exists in 
the output file, that segment is not copied over. 
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The S(elect command causes Library to display a 
prompt asking which code segments to transfer. For 
each code segment not already in the output file, 
Library displays the prompt: Copy from slot 

#_ ?. Pressing or N causes the segment to be 

copied or passed by; pressing E causes the remain¬ 
der of the code segments to be transferred (as in 
E(very); pressing the space bar or the RETURN 
key aborts the S(elect. If the corresponding slot in 
the output file is filled, Library searches for the 
next available slot and places the code there. 

C(omp-unit causes Library to display the prompt: 
Copy what compi l a t ion unit?. The compi¬ 
lation unit named is transferred along with any 
segment procedures that it references. Procedures 
already present in the output file are not copied. 

F(ill does the equivalent of a C(omp-unit command 
for all the compilation units referenced by the seg¬ 
ment references in the output file. 

I(nput allows you to view the next group of seg¬ 
ments in an input file. The Library Utility circularly 
displays 27 segments at a time. If you have over 27 
segments in your input file this allows you to view 
them. 

Ofutput allows you to view the next group of seg¬ 
ments, past the initial 27 segments shown, in your 
output file. The I(nput and 0(utput commands allow 
you to toggle back and forth between groups of 
segments in your files. 




NATIVE CODE GENERATOR 


Native code generator (NCG) is a utility program that translates 
selected portions of an executable p-code file into 8086 native 
code (n-code) on the Texas Instruments Professional Computer. 
Using native code directives inserted into the source code, you 
indicate which portions of the file are to be translated. The result 
of this procedure is an equivalent p-System code file that contains 
p-code and n-code. The NCG translates only valid executable code 
files produced by a UCSD p-System compiler. 

Because n-code generally executes faster than p-code, the NCG 
can be used to speed up the execution of selected portions of p- 
code, for example, portions of code where most of the run-time is 
spent. However, p-code was designed for compactness and conse¬ 
quently takes up less space in memory than n-code. To use the 
NCG effectively, translate only those portions of p-code for which 
execution time is critical. Misuse of the NCG can greatly increase 
the size of the code file. 

You indicate that portions of code are to be translated by insert¬ 
ing native code directives into the Pascal source file before compi¬ 
lation. The following compiler options are the native code 
directives. 

$N+ and $N— 

You insert the first switch {$N+} where the translation should 
begin and the last switch {$N—} where the translation should 
end. When the compiler encounters the first switch, it begins 
generating the additional p-code necessary for n-code generation 
and stops generating when it encounters the last switch. The 
default setting for this compiler option is {$N—}. 
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Native Code Directives and Pascal 

Because the NCG translates a Pascal code file on a proce¬ 
dure by procedure basis, only a complete routine (proce¬ 
dure, function or process) can be translated. One set of 
native code directives may designate more than one pro¬ 
cedure; but the native code generation cannot begin 
within the body of a procedure. The following example 
shows the use of the native code directives in Pascal. 


function MAX (a t b: integer): integer; 

{$N + } 
begin 

if a > b then MAX:= a else MAX:= b; 
end; 

{$N—} 

The object code file, produced by the compiler from 
source code containing native code directives, is an 
executable p-code file that maintains its machine porta¬ 
bility. The only difference is that the native code direc¬ 
tives slightly increase the size of the object code file. 

Running the Native Code Generator 

The NCG is run by executing 8086.NCG.CODE. The 
NCG generates a prompt asking you for an input code file 
and an output code file. The output file must contain the 
suffix .CODE. Only executable code files can be trans¬ 
lated by the NCG (they must be already linked). 

The NCG can produce a formatted listing of the code gen¬ 
erated for each procedure it translates. The NCG gener¬ 
ates a prompt asking you for the name of a listing file. To 
produce a listing, enter a listing file name; for example, 
Console:, Printer:, #5:List, List.Text. To eliminate the 
listing, press the RETURN key in response to the 
prompt. 
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The following listing is an example of function MAX 
translated on the 8086 NCG. 


Final 8086 VERSION NUMBER Code for 


segment M 

procedure 2 segment offset 32 



Source Object 



.RADIX 

10 


P-Code N-Code 


MP 

EQU 

BP 


(Dec. Offsets) 


BASE 

.EQU 

DX 



0| 

ni 



.WORD 

27,0 

4: 

v| 

o| 

A8 

;p-code 

NATIVE 



i| 

8B4604 


MOV 

AX,4(MP] 


4 

3B4602 


CMP 

AX,2[MP] 


7| 

7E08 


JLE 

LI 

9: 

9| 

8B4604 


MOV 

AX,4[MP] 


121 

894606 


MOV 

6[MP],AX 

11: 

15| 

EB06 


JMP 

L2 

13: 

17| 

8B4602 

LI: 

MOV 

AX,2[MP] 


201 

894606 


MOV 

6[MP],AX 

15: 

231 

FF1E0400 

L2: 

CALL 

DS:4 

15: 

271 


;exit code 




27 1 

9602 

;p-code 

RPU 

2 


The preceding listings show the hybrid mixture of p-code 
and n-code produced by the NCG. Cooperation between 
the n-code code and the p-machine interpreter is achieved 
using the following conventions: 

• NATIVE is the p-code that instructs the interpreter 
to start executing n-code. Execution starts on the 
byte following the NATIVE instruction. 

• The header lists the register conventions: p-machine 
registers on the left and processor registers on the 
right. 

• Line L3 contains the instruction that returns the 
processor from n-code to p-code. 

• On the 8086, global and external variables are refer¬ 
enced through register DX, which contains Base. 
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On the whole, the listing looks very much like a listing 
created by the assembler. The following notes may help 
interpret the differences. 

• P-code is preceded by the notation, ;p-code (all other 
instructions are n-code.) 

• The exit code point of the procedure is marked by 
the notation, ;exit code. 

• The left-most column of numbers contains decimal 
byte offsets of equivalent p-code in the original code 
file. These offsets should help identify the source 
code by the offset in the compiler listing. 

• The second column contains decimal byte offsets 
into the final procedure code generated by the NCG. 

Limits of Native Code Generation 

The NCG produces an object code file whose execution 
behavior is identical to the p-code file, except for differ¬ 
ences in execution speed. 

In those instances in which the compiler emits calls to a 
run-time support routine, the NCG leaves the p-code 
intact. Therefore, p-code is used in those places where 
translation would generate excessive code. 

Sequences of straight n-code (code between a NATIVE 
instruction and its matching return instruction, see indi¬ 
vidual processor listings) are treated by the p-machine as 
a single p-code. This fact causes two problems. First, 
although the BRK key may be recognized by the inter¬ 
preter at any point, no further action is taken until the 
next p-code boundary (that is, until the current p-code is 
completed and the next p-code is encountered). Since 
there are no p-code boundaries in n-code, long sequences 
of n-code cannot be terminated by pressing the BRK key. 
Second, p-machine events (interrupts), like the BRK key, 
are only acted upon at p-code boundaries. 
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It is possible to work around these problems. You can 
force a p-code procedure call by calling an empty 
procedure. Since the p-code procedure calls fall into the 
class of p-code that are never translated into n-code by 
the NCG, long sequences of n-code can be broken into 
smaller sequences by a procedure call. Since it is the pro¬ 
cedure call itself that breaks up the sequence, the called 
procedure could be an empty shell. 

Some unusual Pascal constructs create code that the 
NCG will not translate. For example, using the Pascal 
primitive, p- machine, to generate an RPU instruction 
results in the error message: Undefined label. 


PATCH 

The Patch utility enables you to view files and alter them inter 
actively on the byte level. 

Patch is meant to be used interactively with a display unit. It 
uses the screen control module (see UCSD p-System Internal 
Architecture reference manual) to accomplish this; therefore, it 
is terminal-independent (within limitations). 

There are two main facilities in Patch: a mode for editing files on 
the byte level and a mode for dumping files in various formats. 

The byte-editing capability allows you to edit text files, make 
quick fixes to code files, and create specialized test data. 

The dump capability provides formatted dumps in various 
radices. It also allows dumps from main memory. 
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EDIT Mode 


When the system executes Patch, you are in the EDIT 
mode. DUMP is reached by entering D. No information is 
lost in chaining back and forth between the two modes. 

EDIT allows you to open a file or device, read selected 
blocks (specified by relative block number) into an edit 
buffer, either view that buffer or modify it (with TYPE), 
and write the modified block back to the file. The system 
displays buffers on the screen in the desired format; these 
can be edited in a manner similar to using the screen- 
oriented editor. 

The following paragraphs describe the individual com¬ 
mands of the EDIT mode. When it is impossible to per¬ 
form a command, Patch responds with self-explanatory 
error messages. The following lines are the EDIT 
mode menu. 


Edit : DCump, G(et # R(ead, SCave, M < i x , T (y p e , I (n f o , F(or, B(ack f ? 

EDIT : V (i e w , WCipe, QCuit, ? 

The following items explain each menu option. 

D(ump Calls DUMP. 

G(et Opens the file or device and reads 

block zero into the buffer. 

R(ead Reads a specified block from the 

current file. 

S(ave Writes the contents of the buffer out 

to the current block. 

Mfixed Changes the display format for the 

current block. Pressing M toggles to 
change from one format to another: 
hexadecimal or mixed. 




Mixed 

Displays printable ASCII charac¬ 
ters and the hexadecimal equivalent 
of nonprintable characters. 

Hex 

Displays the block in hexadecimal 
digits. 

information 

Displays information about the cur¬ 
rent file including the file name, the 
file length, the number of the cur¬ 
rent block, whether the file is open, 
whether UNITREADs are allowed, 
the device number ( — 1 if UNITIO is 
false), and the byte sex of the cur¬ 
rent machine. 

F(orward 

Gets the next block in the file. 

B(ackward 

Gets the preceding block in the file. 

V(iew 

Displays the current block (see 
M(ixed). 

Wfipedisplay 

Clears the display of the block off 
the display unit. 

Q(uit 

Quits the Patch program. 

T(ype 

Goes into the typing mode, which 
allows the buffer to be edited (de¬ 
scribed in following section). 

TYPE Mode 



The TYPE mode, like the display unit-oriented editor, 
allows the information on the screen to be modified by 
moving the cursor and entering over previously existing 
information. To correct errors made while using the 
TYPE mode, leave the EDIT mode without saving the 
file, read the block over, and try again. 
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The following line is an example of the TYPE mode menu. 


TYPE : C ( h a r , H(ex, F(ill f U(p, D(own, L (e f t , R(ight # <vector 


arrows>, Q (uit 


Character 

Exchanges bytes in the buffer for 
ASCII characters as they are 
pressed, starting from the cursor 
and continuing until you press the 
CONTROL and C keys simultane¬ 
ously (the CONTROL-C key combi¬ 
nation may be referred to as the 

ETX key). Only printable characters 
are accepted. 

H(ex 

Exchanges bytes in the buffer for 
hexadecimal digits as they are 
pressed, starting from the cursor 
and continuing until a Q is pressed; 
(hexadecimal digits can be either 
uppercase or lowercase). 

F(ill 

Fills a portion of the current block 
with the same byte pattern. Accepts 
either ASCII characters or hexadeci¬ 
mal digits for the pattern; upon 
completion, the cursor rests after 
the last byte is filled. 


The following commands move the cursor around within 
the block of displayed data. The cursor is always at a par¬ 
ticular byte. Rather than moving off the screen, the cur¬ 
sor wraps around from side to side and from top to 
bottom. 


U(p 

Moves the cursor up one row. 

D(own 

Moves the cursor down one row. 

L(eft 

Moves the cursor left one column. 
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R(ight Moves the cursor right one column. 

< vector arrows> Moves the cursor in the direction of 
the arrow. 

Q(uit Exits the TYPE mode and returns 

to the EDIT mode. 


DUMP Mode 

You can generate DUMP mode in the following formats: 

• Decimal, hexadecimal, and octal words. 

• ASCII characters, if printable. 

• Decimal (BCD) and octal bytes. 

DUMP can flip the bytes in a word before displaying it or 
simultaneously display a line of words in both flipped and 
nonflipped form. 

Input to the DUMP mode can be a disk file you specify or 
can come directly from main memory. (The DUMP mode 
is used primarily to examine the interpreter and/or the 
Basic Input/Output Subsystem [BIOS].) 

The width of the output can be controlled; a line can con¬ 
tain any number of machine words: 15 words fill a 132- 
character line, and 9 words fill an 80-character line. 

When you enter the DUMP mode, the screen displays 
two options: D(o and Q(uit. Also a lengthy set of format 
specifications are displayed. These can be modified by 
pressing the letter of the item and then entering the speci¬ 
fication. To activate the specification, press D for D(o.* 
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The following list shows the DUMP mode specifications: 

A — The input: A disk file or device. 

B — The number of the block from which dumping starts; 
if (A) is a device, this number is not range-checked. 

C — The number of blocks to print out; if this is too large, 
DUMP merely stops when there are no more blocks to 
output. 

D — Pressing D starts the dump. 

E — A toggle: If true, it reads from main memory; if false, 
it reads from the file in (A). 

F — An offset: The dump may start with a byte that is 
past byte zero; 0 < = (F) < = MAXINT . 

G — The number of bytes to print; < = (G) < = 
MAXINT . 

H — The output file, opened as a text file. 

I — The width of the output line, in machine words; 1 < = 
(IX = 15. 

The following six items have three associated Booleans 
that must be specified: USE, FLIP, and BOTH. 

USE tells DUMP whether or not to use the format asso¬ 
ciated with that item. 

FLIP tells DUMP whether or not to flip the bytes before 
displaying words in that format. 

BOTH tells DUMP to simultaneously display both 
flipped and nonflipped versions of the line. If BOTH is 
true, the value of FLIP does not matter. 

J — Display each word as a decimal integer. 


6-26 






K — Display each word as hexadecimal digits in byte 
order. 

L — Display each word as ASCII characters in byte 
order; nonprintable characters are displayed as hexadeci¬ 
mal digits. 

M — Display each word as an octal integer; this is the 
octal equivalent of (J). 

N — Display each word as decimal bytes (BCD) in byte 
order. 

O — Display each word as octal digits in byte order. 

S — Put a blank line after the nonflipped version of a line. 

T — Put blank lines between different formats of a line. 

U — Pressing Q returns the to EDIT mode; DUMP 
remembers the current specifications. 

Both the EDIT and DUMP modes remember all their 
pertinent information when the other mode is operating. 

Prompts 

All user-supplied numbers used by PATCH are read as 
strings and then converted to integers. Only the first five 
characters of the string are considered. If there are any 
nonnumeric characters in the string, the integer defaults 
to zero. If integer overflow occurs, the integer defaults to 
maxint. (Since integer overflow can only be detected by 
the presence of a negative number, integers in the range 
65536 to 98303 come out modulo 32768.) 
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PRINT SPOOLING 


The print spooler is a program that allows you to queue and print 
files concurrently with the normal execution of the p-System 
(while the console is waiting for input from the keyboard). The 
queue it creates is a file called *SYSTEM.SPOOLER, and the 
files you wish to print must reside on volumes that are on-line or 
an error will occur. 

When SPOOLER is Xfecuted, the following menu appears: 

Spool: PCrint, D(elete, L(ist, SCuspend, RCesume, A(bort, 
C (l e a r ,QCuit 


The following paragraphs explain the items on this menu: 

P(rint Prompts for the name of a file to be printed. This 

name is then added to the queue. If 
*SYSTEM.SPOOLER does not already exist, it is 
created. In the simplest case P(rint can be used to 
send a single file to the printer. Up to 21 files may 
be placed in the print queue. 

D(elete Prompts for a file name to be taken out of the print 
queue. All occurrences of that file name are taken 
out of the queue. 

L(ist Displays the files currently in the queue. 

S(uspend Temporarily halts printing of the current file. 


R(esume Continues printing the current file after a S(uspend. 

R(esume also starts printing the next file in the 
queue after an error or an A(bort. 

A(bort Permanently stops the printing process of the cur¬ 
rent file and takes it out of the queue. 

C(lear Deletes all file names from the queue. 

Q(uit Exits the spooler utility and starts transferring files 

to the printer. 
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If an error occurs (for example, a nonexistent file is specified in 
the queue), the error message appears only when the p-System is 
at the command menu. If necessary, the spooler waits until you 
return to the outer level. 

Program output to the printer can run concurrently with spooled 
output. The spooler finishes the current file and then turns the 
printer over to your program. (Your program is suspended while 
it waits for the printer.) Your program should only do Pascal (or 
other high-level) writes to the printer. If your program does 
printer output using unitwrite , the output is sent immediately 
and appears randomly interspersed with the spooler output. 

The utility SPOOLER.CODE uses the operating system unit 
SPOOLOPS. Within this unit is a process called spooltask. Spool- 
task is started at boot time and runs concurrently with the rest of 
the UCSD p-System. The print spooler automatically restarts at 
boot time if *SYSTEM.SPOOLER is not empty. When the file 
♦SYSTEM.SPOOLER exists, spooltask prints the files that it 
names. Spooltask runs as a background to the main operations of 
the p-System. 

♦SPOOLER.CODE interfaces with SPOOLOPS and uses rou¬ 
tines within it to generate and alter the print queue within 
♦SYSTEM.SPOOLER. 

To restart the print spooling process if SPOOLER.CODE is exe¬ 
cuting when the system goes down, reboot the system, press 
X(ecute from the command menu, enter *SPOOLER.CODE, and 
press the RETURN key. Then press R(esume. 


REALCONV UTILITY 

The REALCONV utility converts real constants in a code file 
from canonical (compiled) form to native machine format. It elim¬ 
inates the need to convert real constants at segment load time, 
thus increasing the initial loading speed of the program seg¬ 
ments, as well as the overall run-time speed of the program. 
This is especially important for programs that require frequent 
loading of segments containing real constants. 
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The real constant conversion utility is a filter that works on code 
files, replacing canonical reals with run-time reals in-place. 
Hence, when the source file is not available, you should make a 
backup copy of the code file to be processed before executing the 
utility program. This avoids destroying the code file while execut¬ 
ing REALCONV with an unsuccessful write. Although slight, 
you should consider this possibility. 

Because the conversion algorithm uses real arithmetic of the host 
processor, the utility must be executed on the processor on which 
the output file will run. In most cases, a code file produced by the 
utility will not run on another processor, which reduces the porta¬ 
bility of otherwise completely transportable code. 

To use the utility, X(ecute REALCONV from the command 
menu. It responds with the following prompt: 


Enter fi le name, <ret> toquit: 


Respond by entering the name of the code file to be processed, fol¬ 
lowed by pressing the RETURN key. You do not have to append 
the suffix .CODE. 

If REALCONV cannot find the file, it prints the message File not 
found and asks you to enter the file name again. Once a correct 
file is entered, REALCONV begins translating. 

If REALCONV cannot complete the conversion successfully, it 
prints a message and stops. The messages can be: 

not enough memory 

error in reading... 

The dots stand for: 
segment dictionaries 
first block 
constant pool 
segment 

(as the case may be), 
error in writing segment 
too many dictionaries 
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Not enough memory means that the segment to be processed is 
larger than the available memory space. 

If the message is error in reading..., X(ecute RE ALCONV again. 

If the message is error in writing segment, then, before X(ecuting 
REALCONV again, you have to restore the code file. Restoring 
the code file depends on the availability of the source file. If the 
source file is available, compile it again and save the code file. If 
only the code file was originally available, make a copy of the 
backup code file. (Remember to backup the original code file.) 

Too many dictionaries means that you have more than 80 seg¬ 
ments in the file. 

The probability of getting any of the three messages is extremely 
slight, but it can happen. 

If REALCONV executes successfully, a dot is written on the 
console for each segment converted; and, once the conversion is 
completed, the message Enter file name: is displayed so you can 
process another file. When there are no more files to process, 
answer the prompt by pressing the RETURN key. This exits 
REALCONV and returns you to the command menu. 


XREF - THE CROSS-REFERENCER 

Introduction 

The procedural cross-referencer (XREF) is a software tool 
that helps you interpret large Pascal program listings. 
The referencer provides a compact summary of the proce¬ 
dure nesting in a program; a list of the procedures; and, 
for each, the procedures that call them. A table of calls 
each procedure made along with all nonlocal variable ref¬ 
erences is also provided. It thus provides information 
about the interprocedural dependencies of a program. 
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Referencer’s Output 


The referencer produces five tables and an optional warn¬ 
ings file: 

• Lexical structure table: summarizes static proce¬ 
dure nesting. 

• Call structure table: lists procedures and the proce¬ 
dures that they call. 

• Procedure call table: presents procedures and the 
procedures that call them. 

• Variable reference table: shows each procedure and 
the variables it references. 

• Variable call table: lists each variable and the proce¬ 
dures which reference or modify it. 

• Warnings file if desired: indicates possible problems 
in the source program. 

Lexical Structure Table 

The first table displays the lexical structure and 
the procedure headings. (The term procedure 
means procedure, function, process or program in 
this document unless otherwise stated.) As the 
system reads the input program, it prints out 
each heading with the line numbers of the lines in 
which it occurs. The text is indented to display 
the lexical nesting. (This indentation must some¬ 
times be compressed to fit on an output line.) 

Referencer considers a procedure heading to be 
any text between the words: procedure, function, 
process, or program—and the semicolon which 
follows. This is not the Pascal definition, but it is 
more useful in debugging programs. If these 
reserved words are embedded within comments, 
they are ignored. 
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The Call Structure Table 


The system produces the second table after it 
scans the program completely. The call structure 
table is the result of examining the internal data. 
For each procedure listed in alphabetical order, 
the table holds: 

• The line-number of the line on which its 
heading starts. 

• Unless it was external or formal (and had no 
corresponding block), the line number of the 
BEGIN that starts its statement part. 

• The characters ext if the procedure has an 
external body (declared with a directive 
other than FORWARD); the characters fml 
if it is a formal procedural or functional par¬ 
ameter; or eh? if it is declared forward with 
no associated forward block or BEGIN. If a 
number appears, the procedure has been 
declared FORWARD and this is the line 
number of the line where the block of the 
procedure begins (that is, the second part of 
the two-part declaration). 

• A list of all user-declared procedures 
directly called by this procedure. (In other 
words, their call is contained in the state¬ 
ment part.) The list is in order of occurrence 
in the text; a procedure is not listed more 
than once. 

• A list of variables referenced by this proce¬ 
dure; and, if nonlocal, the procedure in which 
they were declared. If a variable is modified 
by an assignment, then it is printed with an 
asterisk ( * ) in front of it. 
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The Procedure Call Table 


This table is an alphabetical list of procedures; 
and for each procedure the procedures that call it. 

Variable Reference Table 

This table is an alphabetical list of procedures; 
and, for each procedure, the variables that the 
procedure examines or modifies in any way. If the 
variable is not local to the procedure in question, 
then the procedure in which the variable was 
declared is listed. 

Variable references are shown in three forms: 


< variable name> ::= a local variable 


< procedure name> < variable name> a 
variable defined in <procedure> that is 
used but not modified 



< procedure name> *< variable name> ::= a 
variable defined in < procedure> which is 
modified 


Variable Call Table 


The form of the variable call table is demon¬ 
strated in the following line. 

• < procedure name> < variable name> : 

< procedure name> [< procedure name> ] 


The first procedure name is the procedure that 
owns the variable name, and the following proce¬ 
dure^) either examine or modify that variable. 
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Warnings File 


This file contains warning messages. There are 
three types of warning messages in the warning 
file: 


• Symbol may be undeclared line# xxxx. 

• Symbol may not be initialized line# xxxx. 

• Not standard, nested comments line# xxxx. 

Symbol is an identifier, and xxxx is the number of 
the line on which it occurs. 

Referencer only catches initializations done by 
replacement statements (: = ), so variables that 
are initialized by procedure calls (including 
READ, and so on) are flagged as possibly 
uninitialized. Depending on the program, there 
may be a surplus of such warning messages. 

The Not standard, nested comments warning 
refers to the nesting of comments having differ¬ 
ent bracket types: (*like this {verstehen Sie?}*), 
which is accepted by the UCSD Pascal compiler, 
but not the current International Standards 
Organization (ISO) draft standard. 

The warnings file may only be generated if the 
variable reference table is also generated. 
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Using Referencer 


The referencer has options that are user-defined 
at run-time. When the user executes XREF, refer¬ 
encer displays prompts asking for answers to the 
following questions. 

• How wide is your output device? [40.. 132]: 

This is the length of the output line for the 
available terminal/printer. Suggested out¬ 
put width is 80 characters. 

• Please enter the file you wish cross-refer¬ 
enced: 

The name of the text file that contains the 
Pascal program to be referenced. If the spec¬ 
ified file cannot be successfully opened, the 
prompt is repeated until you enter a valid 
input file name or press the RETURN key. 
Entering an empty file name, (pressing the 
R ETURN key) exits referencer. 

• Is this a compiled listing? [y/n]: 

The program reads either .TEXT files con¬ 
taining Pascal source programs or listing 
files generated by the compiler. Using a 
compiled listing as input assures the user 
that the line numbers referenced are syn¬ 
chronized with the line numbers the compi¬ 
ler generates. 

• Do you want intrinsics listed? [y/n]: 

This allows identifiers such as WRITELN, 
PRED, and GET to be accepted as valid 
symbols. These are then cross-referenced as 
procedures listed outside the lexical nesting 
and, therefore, are not expected to have a 
BEGIN associated with them. 
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Do you want initial procedure nestings? 
[y/n]: 

This generates the lexical structure table. 
This table shows the procedure headings 
and, for each procedure, the list of proce¬ 
dures that it calls. 

Do you want procedure called by trees? 
[y/n]: 

This option is offered only if the lexical 
structure table is desired. A y generates 
both the call structure table and the proce¬ 
dure call table. The procedure call table lists 
each procedure and all of the procedures 
that call it. (A warning is displayed if less 
than 10,000 words of memory are available 
to generate these trees; no provision is made 
for possible stack overflow.) 

Do you want variables referenced? [y/n]: 

A y generates the variable reference table. 

Do you want variable called by trees? [y/n]: 

A v generates the variable call table. 

Do you wish warnings? [y/n]: 

generates the warnings file. This option is 
offered only if the preceding selection was 
made. 

Please enter the name of the warning file: 

If the user selects warnings, then that per¬ 
son has the option of directing the warnings 
to any file. If the file is a disk file, the name 
should have .TEXT appended to it. 




Output File: 


The name of the file to which the user would 
like the output directed. If the file is a disk 
file, the name should have .TEXT appended 
to it. 

The referencer expects to read a complete and 
syntactically correct Pascal program. Although 
results with syntactically incorrect programs are 
not assured, the referencer is not sensitive to 
most flaws. It cares about procedure, function, 
program headings, and about properly matching 
BEGINs and CASEs with ENDs in the state¬ 
ment parts. 

Referencer does not try to format procedure and 
function headings; it leaves them as they were 
entered in the program, except for aligning inden¬ 
tations. 

The tables are all as wide as the output line 
length, as specified by you. Eighty characters is 
usually sufficient. For large programs, the first 
table (the lexical structure table) is clearer with a 
larger print line. 

Limitations 


When presented with incorrect Pascal programs, 
the behavior of referencer is not assured. 
However, it has been designed to be reliable, and 
there are few flaws that can cause it to fail. The 
most critical features are: the general structure of 
procedure headings; and correctly matching an 
END with each BEGIN or CASE in each state¬ 
ment part (since this information is used to detect 
the end of a procedure). 
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If an error is explicitly detected (referencer has 
very few explicit error checks and minimal error- 
recovery), the system displays the following mes¬ 
sage. 


FATAL ERROR - No identi fier after prog/proc/func - At Line No. tttttt 


The line number displayed (###) is the line where 
the program found an error; like all diagnoses this 
does not assure that the correct reason is ascribed 
to the error. Processing continues for a while 
despite the fatal error, but only the lexical struc¬ 
ture table is produced. 

Referencer accepts standard Pascal programs, 
UCSD Pascal Programs, and UCSD Units; it pro¬ 
cesses each correctly. 
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A 


Special Keys 


BACKSPACE 

TAB 

UPARROW 

DOWN ARROW 

LEFT ARROW 

RIGHT ARROW 

RETURN 

ETX 

ESC 

BREAK 

STOP 

FLUSH 

DELETE LINE 
EXCHANGE-INSERT 
EXCHANGE-DELETE 
ALPHA-LOCK 


Backspace 

TAB 


Marked Accordingly 

Return 

CTRL C 

ESC 

Shifted BRK/PAUSE 
Unshifted BRK/PAUSE 
or CTRL S 
CTRL F 

CTRL Backspace 

INS 

DEL 

Uppercase 


The following table describes special keyboard functions and the 
affected keys: 


Keys Pressed 


Function 


ALT 1 

Toggle display intensity (color) 

ALT 2 

Toggle cursor size 

ALT 3 

Toggle cursor state 

ALT 4 

Clear graphics screens 

ALT 5 

Disable function keys 
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The special function keys provides the following features: 


ALT 1 


ALT 2 


ALT 3 


ALT 4 


ALT 5 


The display intensity toggle allows you to set the 
intensity of characters displayed on the gray 
scale monitor. On the high resolution graphics 
monitor, this sets the color of the displayed char¬ 
acters. 

The cursor size toggle allows you to define the 
cursor ranging from no cursor to a full block cur¬ 
sor. 

The cursor state toggle allows you to turn the 
cursor off, cause the cursor to blink rapidly, cause 
the cursor to blink slowly, or cause the cursor to 
be nonblinking. 

The clear graphics display unit function clears the 
installed graphics planes without affecting the 
text display unit. 

The disable function keys toggle allows you to 
enable or disable function keys on the keyboard. 
The affected keys are those that return two char¬ 
acter sequences. These keys are not always appro¬ 
priate and may be confusing when struck in 
certain circumstances since the application pro¬ 
gram will receive two characters which are mean¬ 
ingful only when used as a pair. For example, 
with function keys enabled, the FI key causes the 
assembler to execute when the system is display¬ 
ing the Command menu. The FI key returns the 
characters 27 and 97. The system discards the 27 
as invalid and treats the 97 (lowercase a) as a 
command to begin the assembler. This toggle 
allows you to disable these two key sequences. 
The same keys are used to re-enable the function 
keys when desired. 
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B 


Execution Errors 


0 Fatal system error 

1 Invalid index, value out of range 

2 No segment, bad code file 

3 Procedure not present at exit time 

4 Stack overflow 

5 Integer overflow 

6 Divide by zero 

7 Invalid memory reference < bus timed out> 

8 User break 

9 Fatal system I/O error 

10 User I/O error 

11 Unimplemented instruction 

12 Floating point math error 

13 String too long 

14 Halt, Breakpoint 

15 Bad Block 

All run-time errors cause the system to Unitialize itself; FATAL 
errors cause the system to rebootstrap. Some FATAL errors 
leave the system in an irreparable state, in which case the user 
must rebootstrap. 
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0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 


C 


I/O Results 


No error 

Bad Block, Parity error (CRC) 

Bad Device Number 
Illegal I/O request 
Data-com timeout 
Volume is no longer on-line 
File is no longer in directory 
Bad file name 

No room, insufficient space on volume 

No such volume on-line 

No such file on volume 

Duplicate directory entry 

Not closed: attempt to open an open file 

Not open: attempt to access a closed file 

Bad format: error in reading real or integer 

Ring buffer overflow 

Volume is write-protected 

Illegal block number 

Illegal buffer 
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D 


Device Number Assignments 


The p-System on the Texas Instruments Professional Computer 
supports up to 4 disk drives, a random access memory (RAM) 
disk, a parallel printer, the serial communications option card, 
and up to 10 subsidiary volumes. The following table describes 
the shipped unit number assignments as defined by 
SYSTEM.MISCINFO. 


Device 

Volume 


Number 

Name 

Comment 

1 

CONSOLE 


2 

SYSTERM 


4 

DS01 

Volume name assigned by user 

5 

DS02 

Volume name assigned by user 

6* 

PRINTER 

Optional printer required 

7* 

REMIN 

Optional communications required 

8* 

REMOUT 

Optional communications required 

9* 

DS03 

Optional disk drive required 

10* 

DS04 

Optional disk drive required 

11* 

RAM disk 

Optional memory required 

12 


First user subsidiary vol 

21 


Last user subsidiary vol 

* Support for optional devices 

is included in standard device support. 

However, device not required for system operation. 
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E 


ASCII Codes 


cimal 

Octal 

Hexadecimal 

Character 

0 

000 

00 

NUL 

1 

001 

01 

SOH 

2 

002 

02 

STX 

3 

003 

03 

ETX 

4 

004 

04 

EOT 

5 

005 

05 

ENQ 

6 

006 

06 

ACK 

7 

007 

07 

BEL 

8 

010 

08 

BS 

9 

Oil 

09 

HT 

10 

012 

0A 

LF 

11 

013 

OB 

VT 

12 

014 

OC 

FF 

13 

015 

OD 

CR 

14 

016 

OE 

SO 

15 

017 

OF 

SI 

16 

020 

10 

DLE 

17 

021 

11 

DCl 

18 

022 

12 

DC2 

19 

023 

13 

DC3 

20 

024 

14 

DC4 

21 

025 

15 

NAK 

22 

026 

16 

SYN 

23 

027 

17 

ETB 

24 

030 

18 

CAN 

25 

031 

19 

EM 

26 

032 

1A 

SUB 

27 

033 

IB 

ESC 

28 

034 

1C 

FS 

29 

035 

ID 

GS 

30 

036 

IE 

RS 

31 

037 

IF 

US 

32 

040 

20 

SP 

33 

041 

21 

J 
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Decimal 

Octal 

Hexadecimal 

34 

042 

22 

35 

043 

23 

36 

044 

24 

37 

045 

25 

38 

046 

26 

39 

047 

27 

40 

050 

28 

41 

051 

29 

42 

052 

2A 

43 

053 

2B 

44 

054 

2C 

45 

055 

2D 

46 

056 

2E 

47 

057 

2F 

48 

060 

30 

49 

061 

31 

50 

062 

32 

51 

063 

33 

52 

064 

34 

53 

065 

35 

54 

066 

36 

55 

067 

37 

56 

070 

38 

57 

071 

39 

58 

072 

3A 

59 

073 

3B 

60 

074 

3C 

61 

075 

3D 

62 

076 

3E 

63 

077 

3F 

64 

100 

40 

65 

101 

41 

66 

102 

42 

67 

103 

43 

68 

104 

44 

69 

105 

45 

70 

106 

46 

71 

107 

47 

72 

110 

48 

73 

111 

49 

74 

112 

4A 


Character 


$ 

% 

& 

( 

) 

* 

+ 


/ 

0 

1 

2 

3 

4 

5 

6 

7 

8 
9 


< 

> 

? 


I 

J 
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Decimal 

Octal 

Hexadecimal 

Char 

75 

113 

4B 

K 

76 

114 

4C 

L 

77 

115 

4D 

M 

78 

116 

4E 

N 

79 

117 

4F 

0 

80 

120 

50 

P 

81 

121 

51 

Q 

82 

122 

52 

R 

83 

123 

53 

S 

84 

124 

54 

T 

85 

125 

55 

U 

86 

126 

56 

V 

87 

127 

57 

W 

88 

130 

58 

X 

89 

131 

59 

Y 

90 

132 

5A 

Z 

91 

133 

5B 

[ 

92 

134 

5C 

/ 

93 

135 

5D 

] 

94 

136 

5E 

A 

95 

137 

5F 


96 

140 

60 

< 

97 

141 

61 

a 

98 

142 

62 

b 

99 

143 

63 

c 

100 

144 

64 

d 

101 

145 

65 

e 

102 

146 

66 

f 

103 

147 

67 

g 

104 

150 

68 

h 

105 

151 

69 

i 

106 

152 

6A 

j 

107 

153 

6B 

k 

108 

154 

6C 

1 

109 

155 

6D 

m 

110 

156 

6E 

n 

111 

157 

6F 

0 

112 

160 

70 

P 

113 

161 

71 

q 

114 

162 

72 

r 

115 

163 

73 

s 
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Decimal 

Octal 

Hexadecimal 

Char 

116 

164 

74 

t 

117 

165 

75 

u 

118 

166 

76 

V 

119 

167 

77 

w 

120 

170 

78 

X 

121 

171 

79 

y 

122 

172 

7A 

z 

123 

173 

7B 

{ 

124 

174 

7C 

1 

125 

175 

7D 

} 

126 

176 

7E 

~ 

127 

177 

7F 

D 
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F 


Keyboard Mapping 


The following figures describe the Texas Instruments Profes¬ 
sional Computer keyboard and key code sequences. 

The first figure illustrates the keyboard and shows the characters 
that appear on the key caps. 

The second figure is laid out in the same fashion and indicates the 
key numbers for each of the keys in the first figure. 

The table at the end lists the keys by key number and indicates 
what codes they produce when entered normally or in conjunction 
with CTL, ALT, and SHIFT. 
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Key 

Normal 

Shift 

Control 

Alt 

01 

F5 

101 

* 


88 

* 


98 

★ 

108 

★ 

02 

F6 

102 

★ 


89 

* 


99 

★ 

109 

★ 

03 

F7 

103 

★ 


90 

★ 


100 

★ 

no 

★ 

04 

F8 

104 

* 


91 

* 


101 

★ 

111 

★ 

05 

F9 

105 

* 


92 

* 


102 

★ 

112 

* 

06 

F10 

106 

* 


93 

★ 


103 

★ 

113 

* 

07 

Fll 

108 

* 


08 

* 


10 

★ 

12 

* 

08 

F12 

110 

* 


09 

* 


11 

★ 

13 

* 

09 

1 

49 


i 

33 



_ 




10 

2 

50 


@ 

69 



03 

★ 



11 

3 

51 


# 

35 



_ 


_ 


12 

4 

52 


$ 

36 



_ 




13 

5 

53 


% 

37 



_ 




14 

6 

54 



94 


RS 

30 


125 


15 

7 

55 


& 

38 



— 


126 

★ 

16 

8 

56 


* 

42 



__ 


127 

* 

17 

9 

57 


( 

40 





128 

* 

18 

0 

48 


) 

41 





129 

★ 

19 

- 

45 



95 


US 

31 



* 

20 

= 

61 


+ 

43 



— 


_ 

* 

21 

BS 

08 


BS 

08 


DEL 

127 



* 

22 


96 


- 

126 






★ 

23 

= 

61 


= 

61 


= 

61 


140 

★ 

24 

+ 

43 


+ 

43 


+ 

43 


141 

* 

25 

SP 

32 


SP 

32 


SP 

32 


142 

* 

26 

HT 

09 


Bktab 

15 

* 

HT 

09 


143 

★ 

27 

1 

49 


1 

49 


1 

49 


_ 


28 


— 



__ 



_ 


_ 


29 

0 

48 


0 

48 


0 

48 


_ 


30 

CR 

13 


CR 

13 


CR 

13 


_ 


31 

4 

52 


4 

52 


4 

52 


_ 


32 

5 

53 


5 

53 


5 

53 


_ 


33 

9 

57 


9 

57 


9 

57 


__ 


34 

- 

45 


_ 

45 


_ 

45 


_ 


35 

2 

50 


2 

50 


2 

50 


-- 
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j Key 

Normal 

Shift 

Control 

Alt 

36 


— 



— 



-- 


__ 


37 


— 



— 



-- 


__ 


38 


— 



— 



— 




39 

7 

55 


7 

55 


7 

55 




40 

8 

56 


8 

56 


8 

56 


_ 


41 

6 

54 


6 

54 


6 

54 


_ 


42 

, 

44 


, 

44 


. 

44 


_ 


43 

3 

51 


3 

51 


3 

51 


_ 


44 


46 



46 



46 


__ 


45 


— 



-- 



-- 




46 

C-rt 

67 

★ 


138 

•k 


116 

★ 

78 

* 

47 

Ins 

111 

★ 


40 

* 


41 

* 

42 

* 

48 

Del 

112 

★ 


56 

* 


57 

* 

58 

* 

49 

HT 

09 


BKTAB 

15 


HT 

09 


__ 


50 

q 

113 


Q 

81 


DC1 

17 


16 

* 

51 

w 

119 


W 

87 


ETB 

23 


17 

* 

52 

e 

101 


E 

69 


ENQ 

05 


18 

* 

53 

r 

114 


R 

82 


DC2 

18 


19 

* 

54 

t 

116 


T 

84 


DC 4 

20 


20 

* 

55 

y 

121 


Y 

89 


EM 

25 


21 

* 

56 

u 

117 


U 

89 


NAK 

21 


22 

* 

57 

i 

105 


I 

73 


HT 

09 


23 

* 

58 

0 

111 


0 

79 


SI 

15 


24 

* 

59 

P 

112 


p 

80 


DLE 

16 


25 


60 

1 

91 


1 

123 


ESC 

27 


-- 

* 

61 

1 

93 


1 

125 


GS 

29 



* 

62 

LF 

10 


LF 

10 



117 

★ 

79 

★ 

63 


-- 



-- 



-- 


__ 


64 

C-up 

65 

★ 


136 

* 


132 

k 

73 

* 

65 

ESC 

27 


ESC 

27 


ESC 

27 




66 

a 

97 


A 

65 


SOH 

01 


30 

k 

67 

s 

115 

★ 

S 

83 


DC 3 

19 


31 

* 

68 

d 

100 

★ 

D 

68 


EOT 

04 


32 

* 

69 

f 

102 


F 

70 


ACK 

06 


33 

k 

70 

g 

103 


G 

71 


BEL 

07 


34 

* 
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Key 

Normal 

Shift 

Control 

Alt 

71 

h 

104 


H 

72 


BS 

08 


35 

★ 

72 

j 

106 


J 

74 


LF 

10 


36 

* 

73 

k 

107 


K 

75 


VT 

11 


37 

* 

74 

1 

108 


L 

76 


FF 

12 


38 

* 

75 

; 

59 



58 



__ 


__ 


76 

' 

39 


" 

34 



_ 


__ 


77 

CR 

13 


CR 

13 


CR 

13 


__ 


78 

\ 

92 


124 


FS 

28 


_ 


79 

c-lf 

08 

★ 


139 

★ 


115 

* 

76 

★ 

80 

Home 

107 

★ 


134 

★ 


119 

★ 

133 

•fc 

81 

SP 

32 


SP 

32 


SP 

32 


SP 32 

* 

82 

z 

122 


Z 

90 


SUB 

26 


44 

★ 

83 

X 

120 


X 

88 


CAN 

24 


45 

* 

84 

c 

99 


C 

67 


ETX 

03 


46 

* 

85 

V 

118 


V 

86 


SYN 

22 


47 

* 

86 

b 

98 


B 

66 


STX 

02 


48 

* 

87 

n 

110 


N 

78 


SO 

14 


49 

★ 

88 

m 

109 


M 

77 


CR 

13 


50 

* 

89 


44 


< 

60 



__ 


__ 


90 

Print 

114 

★ 


— 



__ 


__ 


91 


46 


> 

62 



__ 




92 

/ 

47 


? 

63 



__ 




93 


_ 



__ 



_ 




94 


__ 



__ 



__ 


__ 


95 


— 



_ 





__ 


96 

C-dn 

66 

ir 


137 

★ 


118 

★ 

81 

* 

97 


— 



__ 







98 


-- 



_ 



_ 


__ 


99 


— 



_ 







100 

Ppau 

** 


Pbrk 

128 







101 

FI 

59 

* 


84 

★ 


94 

★ 

104 

* 

102 

F2 

60 

★ 


85 

★ 


95 

★ 

105 

* 

103 

F3 

61 

★ 


86 

★ 


96 

* 

106 

★ 

104 

F4 

62 

* 


87 

★ 


97 

* 

107 

* 


* - Preceded by keyboard lead-in 


-- - Key not used, no key code returned to user program 



F-6 










1: 

2: 

3: 

4: 

5: 

6: 

7: 

8: 

9: 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 


G 


Pascal Compiler Syntax Errors 


Error in simple type 
Identifier expected 
unimplemented error 
) expected 
: expected 

Illegal symbol (terminator expected) 

Error in parameter list 
OF expected 
(expected 
Error in type 
[ expected 
] expected 
END expected 
; expected 
Integer expected 
= expected 
BEGIN expected 
Error in declaration part 
error in < field-list> 

. expected 
* expected 

INTERFACE expected 
IMPLEMENTATION expected 
UNIT expected 

Error in constant 
: = expected 
THEN expected 
UNTIL expected 
DO expected 

TO or DOWNTO expected in FOR statement 
IF expected 
FILE expected 

Error in < factor> (bad expression) 

Error in variable 
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60: Must be of type SEMAPHORE 

61: Must be of type PROCESSID 

62: Process not allowed at this nesting level 

63: Only main task may start processes 

101: Identifier declared twice 

102: Low bound exceeds high bound 

103: Identifier is not of the appropriate class 

104: Undeclared identifier 

105: Sign not allowed 

106: Number expected 

107: Incompatible subrange types 

108: File not allowed here 

109: Type must not be real 

110: < tagfield> type must be scalar or subrange 

111: Incompatible with < tagfield> part 

112: Index type must not be real 

113: Index type must be a scalar or a subrange 

114: Base type must not be real 

115: Base type must be a scalar or a subrange 

116: Error in type of standard procedure parameter 

117: Unsatisfied forward reference 

118: Forward reference type identifier in 

variable declaration 

119: Respecified params not OK for a forward 

declared procedure 

120: Function result type must be scalar, subrange 

or pointer 

121: File value parameter not allowed 

122: A forward declared function’s result type cannot 

be respecified 

123: Missing result type in function declaration 

124: F-format for reals only 

125: Error in type of standard procedure parameter 

126: Number of parameters does not agree with 

declaration 

127: Illegal parameter substitution 

128: Result type does not agree with declaration 

129: Type conflict of operands 

130: Expression is not of set type 
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131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 

161 

162 

163 

164 

165 

166 

167 

168 

169 


Tests on equality allowed only 
Strict inclusion not allowed 
File comparison not allowed 
Illegal type of operand(s) 

Type of operand must be Boolean 
Set element type must be scalar or subrange 
Set element types must be compatible 
Type of variable is not array 
Index type is not compatible with the 
declaration 

Type of variable is not record 

Type of variable must be file or pointer 

Illegal parameter solution 

Illegal type of loop control variable 

Illegal type of expression 

Type conflict 

Assignment of files not allowed 
Label type incompatible with selecting 
expression 

Subrange bounds must be scalar 

Index type must be integer 

Assignment to standard function is not allowed 

Assignment to formal function is not allowed 

No such field in this record 

Type error in READ 

Actual parameter must be a variable 

Control variable cannot be formal or nonlocal 

Multidefined case label 

Too many cases in CASE statement 

No such variant in this record 

Real or string tagfields not allowed 

Previous declaration was not forward 

Again forward declared 

Parameter size must be constant 

Missing variant in declaration 

Substitution of standard proc/func not allowed 

Multidefined label 

Multideclared label 

Undeclared label 

Undefined label 

Error in base set 
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170: Value parameter expected 

171: Standard file was redeclared 

172: Undeclared external file 

173: FORTRAN procedure or function expected 

174: Pascal function or procedure expected 

175: Semaphore value parameter not allowed 

176: Undefined forward procedure or function 

182: Nested UNITs not allowed 

183: External declaration not allowed at this 

nesting level 

184: External declaration not allowed in 

INTERFACE section 
185: Segment declaration not allowed in 

INTERFACE section 

186: Labels not allowed in INTERFACE section 

187: Attempt to open library unsuccessful 

188: UNIT not declared in previous uses declaration 

189: USES not allowed at this nesting level 

190: UNIT not in library 

191: Forward declaration was not segment 

192: Forward declaration was segment 

193: Not enough room for this operation 

194: Flag must be declared at top of program 

195: Unit not importable 

201: Error in real number — digit expected 

202: String constant must not exceed source line 

203: Integer constant exceeds range 

204: 8 or 9 in octal number 

250: Too many scopes of nested identifiers 

251: Too many nested procedures or functions 

252: Too many forward references of procedure entries 

253: Procedure too long 

254: Too many long constants in this procedure 

256: Too many external references 

257: Too many externals 

258: Too many local files 

259: Expression too complicated 
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300: Division by zero 

301: No case provided for this value 

302: Index expression out of bounds 

303: Value to be assigned is out of bounds 

304: Element expression out of range 

398: Implementation restriction 

399: Implementation restriction 

400: Illegal character in text 

401: Unexpected end of input 

402: Error in writing code file, not enough room 

403: Error in reading include file 

404: Error in writing list file, not enough room 

405: PROGRAM or UNIT expected 

406: Include file not legal 

407: Include file nesting limit exceeded 

408: INTERFACE section not contained in one file 

409: Unit name reserved for system 

410: Disk error 

500: Assembler error 
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Pascal Compiler Back-End Errors 


The compiler back-end errors can result from a variety of prob¬ 
lems. Basically, they occur when the back-end finds itself or the 
intermediate code file in an unexpected state. (The intermediate 
code file is a file used by the compiler to communicate between 
the front-end and back-end of the compiler. It consists of compiler 
directives intermixed with actual p-code.) Back-end errors can be 
caused by a corrupt intermediate code file, external forces (such 
as bad blocks on the disk), or source file information that is 
skipped by the front-end but used by the back-end. 

The following table lists each of the back-end errors and gives a 
possible explanation for their occurrence: 

Error 

Number Comments 


— 1 While trying to generate the constant pool infor¬ 

mation for a particular code segment, the back¬ 
end tries to read one block from the intermediate 
code file and the read fails. 

1 If the lexical procedure nesting is greater than 31, 

this error will occur. Since the front-end only 
allows nesting of 7 procedures, this error should 
theoretically never occur. 

4 The intermediate code file directives are bytes 
with values greater than 252. If the back-end 
reads a directive with a value that is less than 
253, error number 4 will result. 

5 The current procedure number is greater than the 
maximum number of procedures for that seg¬ 
ment. 
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Error 

Number 


Comments 


6 The operator (variable, constant, jump location) 
that the back-end is trying to remap is not in the 
scope of the compilation unit. 

7 The back-end cannot find the target site to jump 
to while resolving jumps. 

8 There are more than 400 jumps in the jump table 
while trying to enter a site jump error. Try divid¬ 
ing each procedure with many jumps into more 
than one procedure. 

9 There are more than 400 jumps in the jump table 
while trying to enter a target jump. Try dividing 
each procedure with many jumps into more than 
one procedure. 

11 The code pointer is less than zero or greater than 
the length of the intermediate code file while 
building a jump table. 

12 A jump site cannot be found in the jump table. 

22 Unexpected end of input while generating the 
LCO p-code instruction. 

23 Unexpected end of input while generating the 
LDC p-code instruction. 

24 The exit for a certain procedure cannot be found 
in the jump table. 

25 The code pointer is less than zero or greater than 
the length of the intermediate code file while gen¬ 
erating p-code. 

27 The code pointer is less than zero before trying to 

read in more code from the intermediate code file 
to the code buffer. 
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Error 

Number Comments 


28 The code pointer is less than zero after trying to 
read in more code from the intermediate code file 
to the code buffer. 

29 The current final output block number is greater 
than the block number of the intermediate code 
file being processed. 

30 The final code file size exceeds the intermediate 
code file size before trying to write more final 
code. 

31 The final code file size exceeds the intermediate 
code file size after writing more final code. 

41 The line length of a compiled listing exceeds 120 

characters. (Note: This error can occur on a pre- 
IV. 1 compiler if there is an illegal character after 
a DLE character.) 

86 Could not find a particular segment in the inter¬ 

mediate code file. 

99 The number of procedures does not match the 

number specified in the procedure dictionary. 

When you encounter a back-end error: 

• If a syntax error has occurred in the front-end and a back¬ 
end error occurs, fix the syntax error and try recompiling. 

• If there are Bad Blocks on any of the disks being used for 
the compilation replace the bad disks with good ones and 
try recompiling. 
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THREE-MONTH 
LIMITED WARRANTY 
TEXAS INSTRUMENTS 
PROFESSIONAL COMPUTER 
SOFTWARE MEDIA 


TEXAS INSTRUMENTS INCORPORATED EXTENDS 
THIS CONSUMER WARRANTY ONLY TO THE 
ORIGINAL CONSUMER/PURCHASER. 


WARRANTY DURATION 


The media is warranted for a period of three (3) months from 
the date of original purchase by the consumer. 

Some states do not allow the exclusion or limitation of inciden¬ 
tal or consequential damages or limitations on how long an im¬ 
plied warranty lasts, so the above limitations or exclusions 
may not apply to you. 


WARRANTY COVERAGE 


This limited warranty covers the cassette or diskette (media) 
on which the computer program is furnished. It does not ex¬ 
tend to the program contained on the media or the accompany¬ 
ing book materials (collectively the Program). The media is 
warranted against defects in material or workmanship. THIS 
WARRANTY IS VOID IF THE MEDIA HAS BEEN DAM¬ 
AGED BY ACCIDENT, UNREASONABLE USE, NE¬ 
GLECT, IMPROPER SERVICE, OR OTHER CAUSES 
NOT ARISING OUT OF DEFECTS IN MATERIALS OR 
WORKMANSHIP. 




PERFORMANCE BY TI UNDER WARRANTY 


During the above three-month warranty period, defective media 
will be replaced when it is returned postage prepaid to a Texas 
Instruments Service Facility listed below or an authorized 
Texas Instruments Professional Computer Dealer with a copy 
of the purchase receipt. The replacement media will be war¬ 
ranted for three months from date of replacement. Other than 
the postage requirement (where allowed by state law), no 
charge will be made for the replacement. TI strongly recom¬ 
mends that you insure the media for value prior to mailing. 


WARRANTY AND CONSEQUENTIAL 
DAMAGES DISCLAIMERS 


ANY IMPLIED WARRANTIES ARISING OUT OF THIS 
SALE INCLUDING, BUT NOT LIMITED TO, THE IM¬ 
PLIED WARRANTIES OF MERCHANTABILITY AND 
FITNESS FOR A PARTICULAR PURPOSE, ARE LIM¬ 
ITED IN DURATION TO THE ABOVE THREE-MONTH 
PERIOD. TEXAS INSTRUMENTS SHALL NOT BE LI¬ 
ABLE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR 
CONSEQUENTIAL COSTS, EXPENSES, OR DAMAGES 
INCURRED BY THE CONSUMER OR ANY OTHER USER 
ARISING OUT OF THE PURCHASE OR USE OF THE 
MEDIA. THESE EXCLUDED DAMAGES INCLUDE, BUT 
ARE NOT LIMITED BY, COST OF REMOVAL OR REIN¬ 
STALLATION, OUTSIDE COMPUTER TIME, LABOR 
COSTS, LOSS OF GOODWILL, LOSS OF PROFITS, LOSS 
OF SAVINGS, OR LOSS OF USE OR INTERRUPTION OF 
BUSINESS. 


LEGAL REMEDIES 


This warranty gives you specific legal rights, and you may also 
have other rights which vary from state to state. 




TEXAS INSTRUMENTS 
CONSUMER SERVICE FACILITIES 


U.S. Residents: 

Texas Instruments 
Service Facility 
P.O. Box 1444, MS 7758 
Houston, Texas 77001 


Canadian Residents: 

Geophysical Service Inc. 
41 Shelley Road 
Richmond Hill, Ontario 
Canada L4C 5G4 


Consumers in California and Oregon may contact the following 
Texas Instruments offices for additional assistance or 
information. 


Texas Instruments 
Consumer Service 
831 South Douglas St. 

Suite 119 

El Segundo, California 90245 
(213) 973-2591 


Texas Instruments 
Consumer Service 
6700 S.W. 105th 
Kristin Square, Suite 110 
Beaverton, Oregon 97005 
(503) 643-6758 


IMPORTANT NOTICE OF DISCLAIMER 
REGARDING THE PROGRAM 

The following should be read and understood before using the 
software media and Program. 

TI does not warrant that the Program will be free from error or 
will meet the specific requirements of the purchaser/user. The 
purchaser/user assumes complete responsibility for any deci¬ 
sion made or actions taken based on information obtained 
using the Program. Any statements made concerning the util¬ 
ity of the Program are not to be construed as expressed or im¬ 
plied warranties. 






TEXAS INSTRUMENTS MAKES NO WARRANTY, 
EITHER EXPRESSED OR IMPLIED, INCLUDING BUT 
NOT LIMITED TO ANY IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICU¬ 
LAR PURPOSE, REGARDING THE PROGRAM AND 
MAKES ALL PROGRAMS AVAILABLE SOLELY ON AN 
“AS IS” BASIS. 

IN NO EVENT SHALL TEXAS INSTRUMENTS BE LI¬ 
ABLE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR 
CONSEQUENTIAL DAMAGES IN CONNECTION WITH 
OR ARISING OUT OF THE PURCHASE OR USE OF THE 
PROGRAM. THESE EXCLUDED DAMAGES INCLUDE, 
BUT ARE NOT LIMITED BY, COST OF REMOVAL OR 
REINSTALLATION, OUTSIDE COMPUTER TIME, 
LABOR COSTS, LOSS OF GOODWILL, LOSS OF PROFITS, 
LOSS OF SAVINGS, OR LOSS OF USE OR INTERRUP¬ 
TION OF BUSINESS. THE SOLE AND EXCLUSIVE LIA¬ 
BILITY OF TEXAS INSTRUMENTS, REGARDLESS OF 
THE FORM OF ACTION, SHALL NOT EXCEED THE 
PURCHASE PRICE OF THE PROGRAM. TEXAS INSTRU¬ 
MENTS SHALL NOT BE LIABLE FOR ANY CLAIM OF 
ANY KIND WHATSOEVER BY ANY OTHER PARTY 
AGAINST THE PURCHASER/USER OF THE PROGRAM. 


COPYRIGHT 


All Programs are copyrighted. The purchaser/user may not 
make unauthorized copies of the Programs for any reason. The 
right to make copies is subject to applicable copyright law or a 
Program License Agreement contained in the software pack¬ 
age. All authorized copies must include reproduction of the 
copyright notice and of any proprietary rights notice. 
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